Move gtk-doc comments from C files to public header files

Now the documentation lives with the declaration, the C files are
gone and all code parsing tools are happy.

Closes #630 again.

8 files changed, 1264 insertions, 1383 deletions

diff --git a/Makefile.am b/Makefile.am
index cdc509d1..fba87db7 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -23,7 +23,8 @@ bin_PROGRAMS = rsvg-convert
 include rsvg-c-srcs.mk
 
 librsvg_@RSVG_API_MAJOR_VERSION@_la_SOURCES =	\
-	$(librsvg_c_srcs)			\
+	$(librsvg_public_headers)		\
+	$(librsvg_private_headers)		\
 	$(NULL)
 
 LIBRSVG_INTERNALS_SRC =						\
@@ -233,9 +234,7 @@ librsvg_@RSVG_API_MAJOR_VERSION@_la_LIBADD = \
 	$(DLOPEN_LIBS)
 
 librsvgincdir = $(includedir)/librsvg-$(RSVG_API_VERSION)/librsvg
-librsvginc_HEADERS =			\
-	$(headers)			\
-	$(extra_inc_headers)
+librsvginc_HEADERS = $(librsvg_public_headers)
 
 dist_man_MANS = rsvg-convert.1
 
@@ -303,10 +302,7 @@ Rsvg-@RSVG_API_VERSION@.gir: librsvg-@RSVG_API_MAJOR_VERSION@.la
 
 Rsvg_@RSVG_API_VERSION_U@_gir_NAMESPACE = Rsvg
 Rsvg_@RSVG_API_VERSION_U@_gir_EXPORT_PACKAGES = librsvg-$(RSVG_API_VERSION)
-Rsvg_@RSVG_API_VERSION_U@_gir_FILES = \
-	$(librsvginc_HEADERS) \
-	$(filter-out %.h,$(librsvg_@RSVG_API_MAJOR_VERSION@_la_SOURCES)) \
-	$(NULL)
+Rsvg_@RSVG_API_VERSION_U@_gir_FILES = $(librsvginc_HEADERS)
 Rsvg_@RSVG_API_VERSION_U@_gir_INCLUDES = \
 	GLib-2.0 \
 	GObject-2.0 \
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 2da00c96..dbc56e3c 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -52,17 +52,13 @@ FIXXREF_OPTIONS = \
 # Used for dependencies. The docs will be rebuilt if any of these change.
 # e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h
 # e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c
-HFILE_GLOB = \
-	$(top_srcdir)/librsvg/*.h \
-	$(top_builddir)/librsvg/*.h
-
-CFILE_GLOB = \
-	$(top_srcdir)/librsvg/*.c
+HFILE_GLOB = $(top_srcdir)/librsvg/*.h
+CFILE_GLOB =
 
 # Extra header to include when scanning, which are not under DOC_SOURCE_DIR
 # e.g. EXTRA_HFILES=$(top_srcdir}/contrib/extra.h
 # EXTRA_HFILES = $(top_builddir)/evdocument/ev-version.h
-EXTRA_HFILES =
+EXTRA_HFILES = $(top_builddir)/librsvg/rsvg-version.h
 
 # Header files to ignore when scanning. Use base file name, no paths
 # e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
diff --git a/librsvg/rsvg-base.c b/librsvg/rsvg-base.c
deleted file mode 100644
index 7b1bc98b..00000000
--- a/librsvg/rsvg-base.c
+++ /dev/null
@@ -1,89 +0,0 @@
-/* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
-/* vim: set sw=4 sts=4 expandtab: */
-/*
-   rsvg.c: SAX-based renderer for SVG files into a GdkPixbuf.
-
-   Copyright (C) 2000 Eazel, Inc.
-   Copyright (C) 2002 Dom Lachowicz <cinamod@hotmail.com>
-
-   This library is free software; you can redistribute it and/or
-   modify it under the terms of the GNU Lesser General Public
-   License as published by the Free Software Foundation; either
-   version 2.1 of the License, or (at your option) any later version.
-
-   This library 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
-   Lesser General Public License for more details.
-
-   You should have received a copy of the GNU Lesser General Public
-   License along with this library; if not, write to the Free Software
-   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
-
-   Author: Raph Levien <raph@artofcode.com>
-*/
-
-/**
- * rsvg_error_quark:
- *
- * The error domain for RSVG
- *
- * Returns: The error domain
- */
-
-/**
- * rsvg_set_default_dpi:
- * @dpi: Dots Per Inch (aka Pixels Per Inch)
- *
- * Do not use this function.  Create an #RsvgHandle and call
- * rsvg_handle_set_dpi() on it instead.
- *
- * Since: 2.8
- *
- * Deprecated: 2.42.3: This function used to set a global default DPI.  However,
- * it only worked if it was called before any #RsvgHandle objects had been
- * created; it would not work after that.  To avoid global mutable state, please
- * use rsvg_handle_set_dpi() instead.
- */
-
-/**
- * rsvg_set_default_dpi_x_y:
- * @dpi_x: Dots Per Inch (aka Pixels Per Inch)
- * @dpi_y: Dots Per Inch (aka Pixels Per Inch)
- *
- * Do not use this function.  Create an #RsvgHandle and call
- * rsvg_handle_set_dpi_x_y() on it instead.
- *
- * Since: 2.8
- *
- * Deprecated: 2.42.3: This function used to set a global default DPI.  However,
- * it only worked if it was called before any #RsvgHandle objects had been
- * created; it would not work after that.  To avoid global mutable state, please
- * use rsvg_handle_set_dpi() instead.
- */
-
-/**
- * rsvg_init:
- *
- * This function does nothing.
- *
- * Since: 2.9
- * Deprecated: 2.36: There is no need to initialize librsvg.
- **/
-
-/**
- * rsvg_term:
- *
- * This function does nothing.
- *
- * Since: 2.9
- * Deprecated: 2.36: There is no need to de-initialize librsvg.
- **/
-
-/**
- * rsvg_cleanup:
- *
- * Deprecated: 2.46: No-op. This function should not be called from normal programs.
- *
- * Since: 2.36
- **/
diff --git a/librsvg/rsvg-cairo.h b/librsvg/rsvg-cairo.h
index 12d58359..a0ad7612 100644
--- a/librsvg/rsvg-cairo.h
+++ b/librsvg/rsvg-cairo.h
@@ -33,17 +33,131 @@
 
 G_BEGIN_DECLS 
 
+/**
+ * rsvg_handle_render_cairo:
+ * @handle: A #RsvgHandle
+ * @cr: A Cairo context
+ *
+ * Draws a loaded SVG handle to a Cairo context.  Drawing will occur with
+ * respect to the @cr's current transformation:  for example, if the @cr has a
+ * rotated current transformation matrix, the whole SVG will be rotated in the
+ * rendered version.
+ *
+ * This function depends on the #RsvgHandle's DPI to compute dimensions in
+ * pixels, so you should call rsvg_handle_set_dpi() beforehand.
+ *
+ * Note that @cr must be a Cairo context that is not in an error state, that is,
+ * cairo_status() must return #CAIRO_STATUS_SUCCESS for it.  Cairo can set a
+ * context to be in an error state in various situations, for example, if it was
+ * passed an invalid matrix or if it was created for an invalid surface.
+ *
+ * Returns: %TRUE if drawing succeeded; %FALSE otherwise.
+ * Since: 2.14
+ */
 RSVG_API
-gboolean    rsvg_handle_render_cairo     (RsvgHandle *handle, cairo_t *cr);
+gboolean rsvg_handle_render_cairo (RsvgHandle *handle, cairo_t *cr);
+
+/**
+ * rsvg_handle_render_cairo_sub:
+ * @handle: A #RsvgHandle
+ * @cr: A Cairo context
+ * @id: (nullable): An element's id within the SVG, starting with "##" (a single
+ * hash character), for example, "##layer1".  This notation corresponds to a
+ * URL's fragment ID.  Alternatively, pass %NULL to render the whole SVG.
+ *
+ * Draws a subset of a loaded SVG handle to a Cairo context.  Drawing will occur with
+ * respect to the @cr's current transformation:  for example, if the @cr has a
+ * rotated current transformation matrix, the whole SVG will be rotated in the
+ * rendered version.
+ *
+ * This function depends on the #RsvgHandle's DPI to compute dimensions in
+ * pixels, so you should call rsvg_handle_set_dpi() beforehand.
+ *
+ * Note that @cr must be a Cairo context that is not in an error state, that is,
+ * cairo_status() must return #CAIRO_STATUS_SUCCESS for it.  Cairo can set a
+ * context to be in an error state in various situations, for example, if it was
+ * passed an invalid matrix or if it was created for an invalid surface.
+ *
+ * Element IDs should look like an URL fragment identifier; for example, pass
+ * "##foo" (hash <literal>foo</literal>) to get the geometry of the element that
+ * has an <literal>id="foo"</literal> attribute.
+ *
+ * Returns: %TRUE if drawing succeeded; %FALSE otherwise.
+ * Since: 2.14
+ */
 RSVG_API
-gboolean    rsvg_handle_render_cairo_sub (RsvgHandle *handle, cairo_t *cr, const char *id);
+gboolean rsvg_handle_render_cairo_sub (RsvgHandle *handle, cairo_t *cr, const char *id);
 
+/**
+ * rsvg_handle_render_document:
+ * @handle: An #RsvgHandle
+ * @cr: A Cairo context
+ * @viewport: Viewport size at which the whole SVG would be fitted.
+ * @error: (optional): a location to store a #GError, or %NULL
+ *
+ * Renders the whole SVG document fitted to a viewport.
+ *
+ * The @viewport gives the position and size at which the whole SVG
+ * document will be rendered.
+ *
+ * The @cr must be in a #CAIRO_STATUS_SUCCESS state, or this function will not
+ * render anything, and instead will return an error.
+ *
+ * API ordering: This function must be called on a fully-loaded @handle.  See
+ * the section <ulink url="#API-ordering">API ordering</ulink> for details.
+ *
+ * Panics: this function will panic if the @handle is not fully-loaded.
+ *
+ * Since: 2.46
+ */
 RSVG_API
 gboolean rsvg_handle_render_document (RsvgHandle           *handle,
                                       cairo_t              *cr,
                                       const RsvgRectangle  *viewport,
                                       GError              **error);
 
+/**
+ * rsvg_handle_get_geometry_for_layer:
+ * @handle: An #RsvgHandle
+ * @id: (nullable): An element's id within the SVG, starting with "##" (a single
+ * hash character), for example, "##layer1".  This notation corresponds to a
+ * URL's fragment ID.  Alternatively, pass %NULL to compute the geometry for the
+ * whole SVG.
+ * @viewport: Viewport size at which the whole SVG would be fitted.
+ * @out_ink_rect: (out)(optional): Place to store the ink rectangle of the element.
+ * @out_logical_rect: (out)(optional): Place to store the logical rectangle of the element.
+ * @error: (optional): a location to store a #GError, or %NULL
+ *
+ * Computes the ink rectangle and logical rectangle of an SVG element, or the
+ * whole SVG, as if the whole SVG were rendered to a specific viewport.
+ *
+ * Element IDs should look like an URL fragment identifier; for example, pass
+ * "##foo" (hash <literal>foo</literal>) to get the geometry of the element that
+ * has an <literal>id="foo"</literal> attribute.
+ *
+ * The "ink rectangle" is the bounding box that would be painted
+ * for fully- stroked and filled elements.
+ *
+ * The "logical rectangle" just takes into account the unstroked
+ * paths and text outlines.
+ *
+ * Note that these bounds are not minimum bounds; for example,
+ * clipping paths are not taken into account.
+ *
+ * You can pass #NULL for the @id if you want to measure all
+ * the elements in the SVG, i.e. to measure everything from the
+ * root element.
+ *
+ * This operation is not constant-time, as it involves going through all
+ * the child elements.
+ *
+ * API ordering: This function must be called on a fully-loaded @handle.  See
+ * the section <ulink url="#API-ordering">API ordering</ulink> for details.
+ *
+ * Panics: this function will panic if the @handle is not fully-loaded.
+ *
+ * Since: 2.46
+ */
 RSVG_API
 gboolean rsvg_handle_get_geometry_for_layer (RsvgHandle     *handle,
                                              const char     *id,
@@ -52,6 +166,40 @@ gboolean rsvg_handle_get_geometry_for_layer (RsvgHandle     *handle,
                                              RsvgRectangle  *out_logical_rect,
                                              GError        **error);
 
+/**
+ * rsvg_handle_render_layer:
+ * @handle: An #RsvgHandle
+ * @cr: A Cairo context
+ * @id: (nullable): An element's id within the SVG, starting with "##" (a single
+ * hash character), for example, "##layer1".  This notation corresponds to a
+ * URL's fragment ID.  Alternatively, pass %NULL to render the whole SVG document tree.
+ * @viewport: Viewport size at which the whole SVG would be fitted.
+ * @error: (optional): a location to store a #GError, or %NULL
+ *
+ * Renders a single SVG element in the same place as for a whole SVG document.
+ *
+ * This is equivalent to rsvg_handle_render_document(), but it renders only a
+ * single element and its children, as if they composed an individual layer in
+ * the SVG.  The element is rendered with the same transformation matrix as it
+ * has within the whole SVG document.  Applications can use this to re-render a
+ * single element and repaint it on top of a previously-rendered document, for
+ * example.
+ *
+ * Element IDs should look like an URL fragment identifier; for example, pass
+ * "##foo" (hash <literal>foo</literal>) to get the geometry of the element that
+ * has an <literal>id="foo"</literal> attribute.
+ *
+ * You can pass #NULL for the @id if you want to render all
+ * the elements in the SVG, i.e. to render everything from the
+ * root element.
+ *
+ * API ordering: This function must be called on a fully-loaded @handle.  See
+ * the section <ulink url="#API-ordering">API ordering</ulink> for details.
+ *
+ * Panics: this function will panic if the @handle is not fully-loaded.
+ *
+ * Since: 2.46
+ */
 RSVG_API
 gboolean rsvg_handle_render_layer (RsvgHandle           *handle,
                                    cairo_t              *cr,
@@ -59,6 +207,53 @@ gboolean rsvg_handle_render_layer (RsvgHandle           *handle,
                                    const RsvgRectangle  *viewport,
                                    GError              **error);
 
+/**
+ * rsvg_handle_get_geometry_for_element:
+ * @handle: An #RsvgHandle
+ * @id: (nullable): An element's id within the SVG, starting with "##" (a single
+ * hash character), for example, "##layer1".  This notation corresponds to a
+ * URL's fragment ID.  Alternatively, pass %NULL to compute the geometry for the
+ * whole SVG.
+ * @out_ink_rect: (out)(optional): Place to store the ink rectangle of the element.
+ * @out_logical_rect: (out)(optional): Place to store the logical rectangle of the element.
+ * @error: (optional): a location to store a #GError, or %NULL
+ *
+ * Computes the ink rectangle and logical rectangle of a single SVG element.
+ *
+ * While `rsvg_handle_get_geometry_for_layer` computes the geometry of an SVG element subtree with
+ * its transformation matrix, this other function will compute the element's geometry
+ * as if it were being rendered under an identity transformation by itself.  That is,
+ * the resulting geometry is as if the element got extracted by itself from the SVG.
+ *
+ * This function is the counterpart to `rsvg_handle_render_element`.
+ *
+ * Element IDs should look like an URL fragment identifier; for example, pass
+ * "##foo" (hash <literal>foo</literal>) to get the geometry of the element that
+ * has an <literal>id="foo"</literal> attribute.
+ *
+ * The "ink rectangle" is the bounding box that would be painted
+ * for fully- stroked and filled elements.
+ *
+ * The "logical rectangle" just takes into account the unstroked
+ * paths and text outlines.
+ *
+ * Note that these bounds are not minimum bounds; for example,
+ * clipping paths are not taken into account.
+ *
+ * You can pass #NULL for the @id if you want to measure all
+ * the elements in the SVG, i.e. to measure everything from the
+ * root element.
+ *
+ * This operation is not constant-time, as it involves going through all
+ * the child elements.
+ *
+ * API ordering: This function must be called on a fully-loaded @handle.  See
+ * the section <ulink url="#API-ordering">API ordering</ulink> for details.
+ *
+ * Panics: this function will panic if the @handle is not fully-loaded.
+ *
+ * Since: 2.46
+ */
 RSVG_API
 gboolean rsvg_handle_get_geometry_for_element (RsvgHandle     *handle,
                                                const char     *id,
@@ -66,6 +261,41 @@ gboolean rsvg_handle_get_geometry_for_element (RsvgHandle     *handle,
                                                RsvgRectangle  *out_logical_rect,
                                                GError        **error);
 
+/**
+ * rsvg_handle_render_element:
+ * @handle: An #RsvgHandle
+ * @cr: A Cairo context
+ * @id: (nullable): An element's id within the SVG, starting with "##" (a single
+ * hash character), for example, "##layer1".  This notation corresponds to a
+ * URL's fragment ID.  Alternatively, pass %NULL to render the whole SVG document tree.
+ * @element_viewport: Viewport size in which to fit the element
+ * @error: (optional): a location to store a #GError, or %NULL
+ *
+ * Renders a single SVG element to a given viewport
+ *
+ * This function can be used to extract individual element subtrees and render them,
+ * scaled to a given @element_viewport.  This is useful for applications which have
+ * reusable objects in an SVG and want to render them individually; for example, an
+ * SVG full of icons that are meant to be be rendered independently of each other.
+ *
+ * Element IDs should look like an URL fragment identifier; for example, pass
+ * "##foo" (hash <literal>foo</literal>) to get the geometry of the element that
+ * has an <literal>id="foo"</literal> attribute.
+ *
+ * You can pass #NULL for the @id if you want to render all
+ * the elements in the SVG, i.e. to render everything from the
+ * root element.
+ *
+ * The `element_viewport` gives the position and size at which the named element will
+ * be rendered.  FIXME: mention proportional scaling.
+ *
+ * API ordering: This function must be called on a fully-loaded @handle.  See
+ * the section <ulink url="#API-ordering">API ordering</ulink> for details.
+ *
+ * Panics: this function will panic if the @handle is not fully-loaded.
+ *
+ * Since: 2.46
+ */
 RSVG_API
 gboolean rsvg_handle_render_element (RsvgHandle           *handle,
                                      cairo_t              *cr,
diff --git a/librsvg/rsvg-handle.c b/librsvg/rsvg-handle.c
deleted file mode 100644
index 3f567443..00000000
--- a/librsvg/rsvg-handle.c
+++ /dev/null
@@ -1,1102 +0,0 @@
-/* -*- Mode: C; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
-/* vim: set sw=4 sts=4 expandtab: */
-/*
-   rsvg-gobject.c: GObject support.
-
-   Copyright (C) 2006 Robert Staudinger <robert.staudinger@gmail.com>
-
-   This library is free software; you can redistribute it and/or
-   modify it under the terms of the GNU Lesser General Public
-   License as published by the Free Software Foundation; either
-   version 2.1 of the License, or (at your option) any later version.
-
-   This library 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
-   Lesser General Public License for more details.
-
-   You should have received a copy of the GNU Lesser General Public
-   License along with this library; if not, write to the Free Software
-   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
-*/
-
-/**
- * SECTION: rsvg-handle
- * @short_description: Loads SVG data into memory.
- *
- * This is the main entry point into the librsvg library.  An RsvgHandle is an
- * object that represents SVG data in memory.  Your program creates an
- * RsvgHandle from an SVG file, or from a memory buffer that contains SVG data,
- * or in the most general form, from a #GInputStream that will provide SVG data.
- *
- * Librsvg can load SVG images and render them to Cairo surfaces,
- * using a mixture of SVG's [static mode] and [secure static mode].
- * Librsvg does not do animation nor scripting, and can load
- * references to external data only in some situations; see below.
- *
- * Librsvg supports reading <ulink
- * url="https://www.w3.org/TR/SVG11/">SVG 1.1</ulink> data, and is
- * gradually adding support for features in <ulink
- * url="https://www.w3.org/TR/SVG2/">SVG 2</ulink>.  Librsvg also supports
- * SVGZ files, which are just an SVG stream compressed with the GZIP algorithm.
- *
- * # The "base file" and resolving references to external files
- *
- * When you load an SVG, librsvg needs to know the location of the "base file"
- * for it.  This is so that librsvg can determine the location of referenced
- * entities.  For example, say you have an SVG in <filename>/foo/bar/foo.svg</filename>
- * and that it has an image element like this:
- *
- * |[
- * <image href="resources/foo.png" .../>
- * ]|
- *
- * In this case, librsvg needs to know the location of the toplevel
- * <filename>/foo/bar/foo.svg</filename> so that it can generate the appropriate
- * reference to <filename>/foo/bar/resources/foo.png</filename>.
- *
- * ## Security and locations of referenced files
- *
- * When processing an SVG, librsvg will only load referenced files if they are
- * in the same directory as the base file, or in a subdirectory of it.  That is,
- * if the base file is <filename>/foo/bar/baz.svg</filename>, then librsvg will
- * only try to load referenced files (from SVG's
- * <literal>&lt;image&gt;</literal> element, for example, or from content
- * included through XML entities) if those files are in <filename>/foo/bar/<!--
- * -->*</filename> or in <filename>/foo/bar/<!-- -->*<!-- -->/.../<!--
- * -->*</filename>.  This is so that malicious SVG files cannot include files
- * that are in a directory above.
- *
- * The full set of rules for deciding which URLs may be loaded is as follows;
- * they are applied in order.  A referenced URL will not be loaded as soon as
- * one of these rules fails:
- *
- * <orderedlist>
- *   <listitem>
- *     All <literal>data:</literal> URLs may be loaded.  These are sometimes used
- *     to include raster image data, encoded as base-64, directly in an SVG file.
- *   </listitem>
- *
- *   <listitem>
- *     All other URL schemes in references require a base URL.  For
- *     example, this means that if you load an SVG with
- *     rsvg_handle_new_from_data() without calling rsvg_handle_set_base_uri(),
- *     then any referenced files will not be allowed (e.g. raster images to be
- *     loaded from other files will not work).
- *   </listitem>
- *
- *   <listitem>
- *     If referenced URLs are absolute, rather than relative, then they must
- *     have the same scheme as the base URL.  For example, if the base URL has a
- *     "<literal>file</literal>" scheme, then all URL references inside the SVG must
- *     also have the "<literal>file</literal>" scheme, or be relative references which
- *     will be resolved against the base URL.
- *   </listitem>
- *
- *   <listitem>
- *     If referenced URLs have a "<literal>resource</literal>" scheme, that is,
- *     if they are included into your binary program with GLib's resource
- *     mechanism, they are allowed to be loaded (provided that the base URL is
- *     also a "<literal>resource</literal>", per the previous rule).
- *   </listitem>
- *
- *   <listitem>
- *     Otherwise, non-<literal>file</literal> schemes are not allowed.  For
- *     example, librsvg will not load <literal>http</literal> resources, to keep
- *     malicious SVG data from "phoning home".
- *   </listitem>
- *
- *   <listitem>
- *     A relative URL must resolve to the same directory as the base URL, or to
- *     one of its subdirectories.  Librsvg will canonicalize filenames, by
- *     removing ".." path components and resolving symbolic links, to decide whether
- *     files meet these conditions.
- *   </listitem>
- * </orderedlist>
- *
- * # Loading an SVG with GIO
- *
- * This is the easiest and most resource-efficient way of loading SVG data into
- * an #RsvgHandle.
- *
- * If you have a #GFile that stands for an SVG file, you can simply call
- * rsvg_handle_new_from_gfile_sync() to load an RsvgHandle from it.
- *
- * Alternatively, if you have a #GInputStream, you can use
- * rsvg_handle_new_from_stream_sync().
- *
- * Both of those methods allow specifying a #GCancellable, so the loading
- * process can be cancelled from another thread.
- *
- * ## Loading an SVG from memory
- *
- * If you already have SVG data in a byte buffer in memory, you can create a
- * memory input stream with g_memory_input_stream_new_from_data() and feed that
- * to rsvg_handle_new_from_stream_sync().
- *
- * Note that in this case, it is important that you specify the base_file for
- * the in-memory SVG data.  Librsvg uses the base_file to resolve links to
- * external content, like raster images.
- *
- * # Loading an SVG without GIO
- *
- * You can load an RsvgHandle from a simple filename or URI with
- * rsvg_handle_new_from_file().  Note that this is a blocking operation; there
- * is no way to cancel it if loading a remote URI takes a long time.  Also, note that
- * this method does not let you specify #RsvgHandleFlags.
- *
- * Otherwise, loading an SVG without GIO is not recommended, since librsvg will
- * need to buffer your entire data internally before actually being able to
- * parse it.  The deprecated way of doing this is by creating a handle with
- * rsvg_handle_new() or rsvg_handle_new_with_flags(), and then using
- * rsvg_handle_write() and rsvg_handle_close() to feed the handle with SVG data.
- * Still, please try to use the GIO stream functions instead.
- *
- * # Resolution of the rendered image (dots per inch, or DPI)
- *
- * SVG images can contain dimensions like "<literal>5 cm</literal>" or
- * "<literal>2 pt</literal>" that must be converted from physical units into
- * device units.  To do this, librsvg needs to know the actual dots per inch
- * (DPI) of your target device.  You can call rsvg_handle_set_dpi() or
- * rsvg_handle_set_dpi_x_y() on an RsvgHandle to set the DPI before rendering
- * it.
- *
- * # Rendering
- *
- * The preferred way to render an already-loaded RsvgHandle is to use
- * rsvg_handle_render_cairo().  Please see its documentation for details.
- *
- * Alternatively, you can use rsvg_handle_get_pixbuf() to directly obtain a
- * #GdkPixbuf with the rendered image.  This is simple, but it does not let you
- * control the size at which the SVG will be rendered.  It will just be rendered
- * at the size which rsvg_handle_get_dimensions() would return, which depends on
- * the dimensions that librsvg is able to compute from the SVG data.
- *
- * # API ordering
- *
- * Due to the way the librsvg API evolved over time, an #RsvgHandle object is available
- * for use as soon as it is constructed.  However, not all of its methods can be
- * called at any time.  For example, an #RsvgHandle just constructed with rsvg_handle_new()
- * is not loaded yet, and it does not make sense to call rsvg_handle_get_dimensions() on it
- * just at that point.
- *
- * The documentation for the available methods in #RsvgHandle may mention that a particular
- * method is only callable on a "fully loaded handle".  This means either:
- *
- * <itemizedlist>
- *   <listitem>
- *     The handle was loaded with rsvg_handle_write() and rsvg_handle_close(), and
- *     those functions returned no errors.
- *   </listitem>
- *   <listitem>
- *     The handle was loaded with rsvg_handle_read_stream_sync() and that function
- *     returned no errors.
- *   </listitem>
- * </itemizedlist>
- *
- * Before librsvg 2.46, the library did not fully verify that a handle was in a
- * fully loaded state for the methods that require it.  To preserve
- * compatibility with old code which inadvertently called the API without
- * checking for errors, or which called some methods outside of the expected
- * order, librsvg will just emit a g_critical() message in those cases.
- *
- * New methods introduced in librsvg 2.46 and later will check for the correct
- * ordering, and panic if they are called out of order.  This will abort
- * the program as if it had a failed assertion.
- */
-
-/***** Begin documentation for RsvgHandle properties *****/
-
-/**
- * RsvgHandle:flags:
- *
- * Flags from #RsvgHandleFlags.
- *
- * Since: 2.36
- */
-
-/**
- * RsvgHandle::dpi-x:
- *
- * Horizontal resolution in dots per inch.
- */
-
-/**
- * RsvgHandle::dpi-y:
- *
- * Horizontal resolution in dots per inch.
- */
-
-/**
- * RsvgHandle::base-uri:
- *
- * Base URI, to be used to resolve relative references for resources.  See the section
- */
-
-/**
- * RsvgHandle:width:
- *
- * Width, in pixels, of the rendered SVG after calling the size callback
- * as specified by rsvg_handle_set_size_callback().
- *
- * 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.
- */
-
-/**
- * RsvgHandle:height:
- *
- * Height, in pixels, of the rendered SVG after calling the size callback
- * as specified by rsvg_handle_set_size_callback().
- *
- * 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.
- */
-
-/**
- * RsvgHandle:em:
- *
- * Exact width, in pixels, of the rendered SVG before calling the size callback
- * as specified by rsvg_handle_set_size_callback().
- *
- * 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.
- */
-
-/**
- * RsvgHandle:ex:
- *
- * Exact height, in pixels, of the rendered SVG before calling the size callback
- * as specified by rsvg_handle_set_size_callback().
- *
- * 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.
- */
-
-/**
- * RsvgHandle:title:
- *
- * SVG's title.
- *
- * Deprecated: 2.36.  Reading this property always returns #NULL.
- */
-
-/**
- * RsvgHandle:desc:
- *
- * SVG's description.
- *
- * Deprecated: 2.36.  Reading this property always returns #NULL.
- */
-
-/**
- * RsvgHandle:metadata:
- *
- * SVG's metadata
- *
- * Deprecated: 2.36.  Reading this property always returns #NULL.
- */
-
-/***** End documentation for RsvgHandle properties *****/
-
-/**
- * rsvg_handle_free:
- * @handle: An #RsvgHandle
- *
- * Frees @handle.
- * Deprecated: Use g_object_unref() instead.
- **/
-
-/**
- * rsvg_handle_new:
- *
- * Returns a new rsvg handle.  Must be freed with @g_object_unref.  This
- * handle can be used to load an image.
- *
- * The preferred way of loading SVG data into the returned #RsvgHandle is with
- * rsvg_handle_read_stream_sync().
- *
- * The deprecated way of loading SVG data is with rsvg_handle_write() and
- * rsvg_handle_close(); note that these require buffering the entire file
- * internally, and for this reason it is better to use the stream functions:
- * rsvg_handle_new_from_stream_sync(), rsvg_handle_read_stream_sync(), or
- * rsvg_handle_new_from_gfile_sync().
- *
- * After loading the #RsvgHandle with data, you can render it using Cairo or get
- * a GdkPixbuf from it. When finished, free the handle with g_object_unref(). No
- * more than one image can be loaded with one handle.
- *
- * Note that this function creates an #RsvgHandle with no flags set.  If you
- * require any of #RsvgHandleFlags to be set, use any of
- * rsvg_handle_new_with_flags(), rsvg_handle_new_from_stream_sync(), or
- * rsvg_handle_new_from_gfile_sync().
- *
- * Returns: A new #RsvgHandle with no flags set.
- **/
-
-/**
- * rsvg_handle_new_from_data:
- * @data: (array length=data_len): The SVG data
- * @data_len: The length of @data, in bytes
- * @error: (optional): return location for errors
- *
- * Loads the SVG specified by @data.  Note that this function creates an
- * #RsvgHandle without a base URL, and without any #RsvgHandleFlags.  If you
- * need these, use rsvg_handle_new_from_stream_sync() instead by creating
- * a #GMemoryInputStream from your data.
- *
- * Returns: A #RsvgHandle or %NULL if an error occurs.
- * Since: 2.14
- */
-
-/**
- * rsvg_handle_new_from_file:
- * @filename: The file name to load, or a URI.
- * @error: (optional): return location for errors
- *
- * Loads the SVG specified by @file_name.  Note that this function, like
- * rsvg_handle_new(), does not specify any loading flags for the resulting
- * handle.  If you require the use of #RsvgHandleFlags, use
- * rsvg_handle_new_from_gfile_sync().
- *
- * Returns: A #RsvgHandle or %NULL if an error occurs.
- * Since: 2.14
- */
-
-/**
- * rsvg_handle_new_with_flags:
- * @flags: flags from #RsvgHandleFlags
- *
- * Creates a new #RsvgHandle with flags @flags.  After calling this function,
- * you can feed the resulting handle with SVG data by using
- * rsvg_handle_read_stream_sync().
- *
- * Returns: (transfer full): a new #RsvgHandle
- *
- * Since: 2.36
- **/
-
-/**
- * rsvg_handle_new_from_gfile_sync:
- * @file: a #GFile
- * @flags: flags from #RsvgHandleFlags
- * @cancellable: (nullable): a #GCancellable, or %NULL
- * @error: (optional): a location to store a #GError, or %NULL
- *
- * Creates a new #RsvgHandle for @file.
- *
- * This function sets the "base file" of the handle to be @file itself, so SVG
- * elements like <literal>&lt;image&gt;</literal> which reference external
- * resources will be resolved relative to the location of @file.
- *
- * If @cancellable is not %NULL, then the operation can be cancelled by
- * triggering the cancellable object from another thread. If the
- * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
- * returned in @error.
- *
- * Returns: a new #RsvgHandle on success, or %NULL with @error filled in
- *
- * Since: 2.32
- */
-
-/**
- * rsvg_handle_new_from_stream_sync:
- * @input_stream: a #GInputStream
- * @base_file: (nullable): a #GFile, or %NULL
- * @flags: flags from #RsvgHandleFlags
- * @cancellable: (nullable): a #GCancellable, or %NULL
- * @error: (optional): a location to store a #GError, or %NULL
- *
- * Creates a new #RsvgHandle for @stream.
- *
- * This function sets the "base file" of the handle to be @base_file if
- * provided.  SVG elements like <literal>&lt;image&gt;</literal> which reference
- * external resources will be resolved relative to the location of @base_file.
- *
- * If @cancellable is not %NULL, then the operation can be cancelled by
- * triggering the cancellable object from another thread. If the
- * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
- * returned in @error.
- *
- * Returns: a new #RsvgHandle on success, or %NULL with @error filled in
- *
- * Since: 2.32
- */
-
-/**
- * rsvg_handle_write:
- * @handle: an #RsvgHandle
- * @buf: (array length=count) (element-type guchar): pointer to svg data
- * @count: length of the @buf buffer in bytes
- * @error: (optional): a location to store a #GError, or %NULL
- *
- * Loads the next @count bytes of the image.
- *
- * Before calling this function for the first time, you may need to call
- * rsvg_handle_set_base_uri() or rsvg_handle_set_base_gfile() to set the "base
- * file" for resolving references to external resources.  SVG elements like
- * <literal>&lt;image&gt;</literal> which reference external resources will be
- * resolved relative to the location you specify with those functions.
- *
- * Returns: %TRUE on success, or %FALSE on error.
- *
- * Deprecated: 2.46.  Use rsvg_handle_read_stream_sync() or the constructor
- * functions rsvg_handle_new_from_gfile_sync() or
- * rsvg_handle_new_from_stream_sync().  This function is deprecated because it
- * will accumulate data from the @buf in memory until rsvg_handle_close() gets
- * called.  To avoid a big temporary buffer, use the suggested functions, which
- * take a #GFile or a #GInputStream and do not require a temporary buffer.
- **/
-
-/**
- * rsvg_handle_close:
- * @handle: a #RsvgHandle
- * @error: (optional): a location to store a #GError, or %NULL
- *
- * Closes @handle, to indicate that loading the image is complete.  This will
- * return %TRUE if the loader closed successfully and the SVG data was parsed
- * correctly.  Note that @handle isn't freed until @g_object_unref is called.
- *
- * Returns: %TRUE on success, or %FALSE on error.
- *
- * Deprecated: 2.46.  Use rsvg_handle_read_stream_sync() or the constructor
- * functions rsvg_handle_new_from_gfile_sync() or
- * rsvg_handle_new_from_stream_sync().  See the deprecation notes for
- * rsvg_handle_write() for more information.
- **/
-
-/**
- * rsvg_handle_read_stream_sync:
- * @handle: a #RsvgHandle
- * @stream: a #GInputStream
- * @cancellable: (nullable): a #GCancellable, or %NULL
- * @error: (optional): a location to store a #GError, or %NULL
- *
- * Reads @stream and writes the data from it to @handle.
- *
- * Before calling this function, you may need to call rsvg_handle_set_base_uri()
- * or rsvg_handle_set_base_gfile() to set the "base file" for resolving
- * references to external resources.  SVG elements like
- * <literal>&lt;image&gt;</literal> which reference external resources will be
- * resolved relative to the location you specify with those functions.
- *
- * If @cancellable is not %NULL, then the operation can be cancelled by
- * triggering the cancellable object from another thread. If the
- * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
- * returned.
- *
- * Returns: %TRUE if reading @stream succeeded, or %FALSE otherwise
- *   with @error filled in
- *
- * Since: 2.32
- */
-
-/**
- * rsvg_handle_set_base_uri:
- * @handle: A #RsvgHandle
- * @base_uri: The base uri
- *
- * Set the base URI for this SVG.
- *
- * Note: This function may only be called before rsvg_handle_write() or
- * rsvg_handle_read_stream_sync() have been called.
- *
- * Since: 2.9
- */
-
-/**
- * rsvg_handle_set_base_gfile:
- * @handle: a #RsvgHandle
- * @base_file: a #GFile
- *
- * Set the base URI for @handle from @file.
- *
- * Note: This function may only be called before rsvg_handle_write() or
- * rsvg_handle_read_stream_sync() have been called.
- *
- * Since: 2.32
- */
-
-/**
- * rsvg_handle_get_base_uri:
- * @handle: A #RsvgHandle
- *
- * Gets the base uri for this #RsvgHandle.
- *
- * Returns: the base uri, possibly null
- * Since: 2.8
- */
-
-/**
- * rsvg_handle_set_stylesheet:
- * @handle: A #RsvgHandle.
- * @css: (array length=css_len): String with CSS data; must be valid UTF-8.
- * @css_len: Length of the @css data in bytes.
- * @error: (optional): return location for errors.
- *
- * Sets a CSS stylesheet to use for an SVG document.
- *
- * The @css_len argument is mandatory; this function will not compute the length
- * of the @css string.  This is because a provided stylesheet, which the calling
- * program could read from a file, can have nul characters in it.
- *
- * During the CSS cascade, the specified stylesheet will be used with a "User"
- * <ulink
- * url="https://drafts.csswg.org/css-cascade-3/#cascading-origins">origin</ulink>.
- *
- * Note that `@import` rules will not be resolved, except for `data:` URLs.
- *
- * Since: 2.48
- */
-
-/**
- * rsvg_handle_get_metadata:
- * @handle: An #RsvgHandle
- *
- * Returns: (nullable): This function always returns #NULL.
- *
- * Since: 2.9
- *
- * Deprecated: 2.36.  Librsvg does not read the metadata/desc/title elements;
- * this function always returns #NULL.
- */
-
-/**
- * rsvg_handle_get_title:
- * @handle: An #RsvgHandle
- *
- * Returns: (nullable): This function always returns NULL.
- *
- * Since: 2.4
- *
- * Deprecated: 2.36.  Librsvg does not read the metadata/desc/title elements;
- * this function always returns #NULL.
- */
-
-/**
- * rsvg_handle_get_desc:
- * @handle: An #RsvgHandle
- *
- * Returns: (nullable): This function always returns NULL.
- *
- * Since: 2.4
- *
- * Deprecated: 2.36.  Librsvg does not read the metadata/desc/title elements;
- * this function always returns #NULL.
- */
-
-/**
- * rsvg_handle_render_cairo_sub:
- * @handle: A #RsvgHandle
- * @cr: A Cairo context
- * @id: (nullable): An element's id within the SVG, starting with "##" (a single
- * hash character), for example, "##layer1".  This notation corresponds to a
- * URL's fragment ID.  Alternatively, pass %NULL to render the whole SVG.
- *
- * Draws a subset of a loaded SVG handle to a Cairo context.  Drawing will occur with
- * respect to the @cr's current transformation:  for example, if the @cr has a
- * rotated current transformation matrix, the whole SVG will be rotated in the
- * rendered version.
- *
- * This function depends on the #RsvgHandle's DPI to compute dimensions in
- * pixels, so you should call rsvg_handle_set_dpi() beforehand.
- *
- * Note that @cr must be a Cairo context that is not in an error state, that is,
- * cairo_status() must return #CAIRO_STATUS_SUCCESS for it.  Cairo can set a
- * context to be in an error state in various situations, for example, if it was
- * passed an invalid matrix or if it was created for an invalid surface.
- *
- * Element IDs should look like an URL fragment identifier; for example, pass
- * "##foo" (hash <literal>foo</literal>) to get the geometry of the element that
- * has an <literal>id="foo"</literal> attribute.
- *
- * Returns: %TRUE if drawing succeeded; %FALSE otherwise.
- * Since: 2.14
- */
-
-/**
- * rsvg_handle_render_cairo:
- * @handle: A #RsvgHandle
- * @cr: A Cairo context
- *
- * Draws a loaded SVG handle to a Cairo context.  Drawing will occur with
- * respect to the @cr's current transformation:  for example, if the @cr has a
- * rotated current transformation matrix, the whole SVG will be rotated in the
- * rendered version.
- *
- * This function depends on the #RsvgHandle's DPI to compute dimensions in
- * pixels, so you should call rsvg_handle_set_dpi() beforehand.
- *
- * Note that @cr must be a Cairo context that is not in an error state, that is,
- * cairo_status() must return #CAIRO_STATUS_SUCCESS for it.  Cairo can set a
- * context to be in an error state in various situations, for example, if it was
- * passed an invalid matrix or if it was created for an invalid surface.
- *
- * Returns: %TRUE if drawing succeeded; %FALSE otherwise.
- * Since: 2.14
- */
-
-/**
- * rsvg_handle_get_dimensions:
- * @handle: A #RsvgHandle
- * @dimension_data: (out): A place to store the SVG's size
- *
- * Get the SVG's size. Do not call from within the size_func callback, because
- * an infinite loop will occur.
- *
- * This function depends on the #RsvgHandle's DPI to compute dimensions in
- * pixels, so you should call rsvg_handle_set_dpi() beforehand.
- *
- * Since: 2.14
- */
-
-/**
- * rsvg_handle_get_dimensions_sub:
- * @handle: A #RsvgHandle
- * @dimension_data: (out): A place to store the SVG's size
- * @id: (nullable): An element's id within the SVG, starting with "##" (a single
- * hash character), for example, "##layer1".  This notation corresponds to a
- * URL's fragment ID.  Alternatively, pass %NULL to use the whole SVG.
- *
- * Get the size of a subelement of the SVG file. Do not call from within the
- * size_func callback, because an infinite loop will occur.
- *
- * This function depends on the #RsvgHandle's DPI to compute dimensions in
- * pixels, so you should call rsvg_handle_set_dpi() beforehand.
- *
- * Element IDs should look like an URL fragment identifier; for example, pass
- * "##foo" (hash <literal>foo</literal>) to get the geometry of the element that
- * has an <literal>id="foo"</literal> attribute.
- *
- * Deprecated: 2.46.  Use rsvg_handle_get_geometry_for_layer() instead.
- *
- * Since: 2.22
- */
-
-/**
- * rsvg_handle_get_position_sub:
- * @handle: A #RsvgHandle
- * @position_data: (out): A place to store the SVG fragment's position.
- * @id: (nullable): An element's id within the SVG, starting with "##" (a single
- * hash character), for example, "##layer1".  This notation corresponds to a
- * URL's fragment ID.  Alternatively, pass %NULL to use the whole SVG.
- *
- * Get the position of a subelement of the SVG file. Do not call from within
- * the size_func callback, because an infinite loop will occur.
- *
- * This function depends on the #RsvgHandle's DPI to compute dimensions in
- * pixels, so you should call rsvg_handle_set_dpi() beforehand.
- *
- * Element IDs should look like an URL fragment identifier; for example, pass
- * "##foo" (hash <literal>foo</literal>) to get the geometry of the element that
- * has an <literal>id="foo"</literal> attribute.
- *
- * Deprecated: 2.46.  Use rsvg_handle_get_geometry_for_layer() instead.
- *
- * Since: 2.22
- */
-
-/**
- * rsvg_handle_has_sub:
- * @handle: a #RsvgHandle
- * @id: An element's id within the SVG, starting with "##" (a single hash
- * character), for example, "##layer1".  This notation corresponds to a URL's
- * fragment ID.
- *
- * Checks whether the element @id exists in the SVG document.
- *
- * Element IDs should look like an URL fragment identifier; for example, pass
- * "##foo" (hash <literal>foo</literal>) to get the geometry of the element that
- * has an <literal>id="foo"</literal> attribute.
- *
- * Returns: %TRUE if @id exists in the SVG document, %FALSE otherwise.
- *
- * Since: 2.22
- */
-
-/**
- * rsvg_handle_get_pixbuf_sub:
- * @handle: An #RsvgHandle
- * @id: (nullable): An element's id within the SVG, starting with "##" (a single
- * hash character), for example, "##layer1".  This notation corresponds to a
- * URL's fragment ID.  Alternatively, pass %NULL to use the whole SVG.
- *
- * Creates a #GdkPixbuf the same size as the entire SVG loaded into @handle, but
- * only renders the sub-element that has the specified @id (and all its
- * sub-sub-elements recursively).  If @id is #NULL, this function renders the
- * whole SVG.
- *
- * This function depends on the #RsvgHandle's DPI to compute dimensions in
- * pixels, so you should call rsvg_handle_set_dpi() beforehand.
- *
- * If you need to render an image which is only big enough to fit a particular
- * sub-element of the SVG, consider using rsvg_handle_render_cairo_sub(), upon a
- * surface that is just the size returned by rsvg_handle_get_dimensions_sub().
- * You will need to offset the rendering by the amount returned in
- * rsvg_handle_get_position_sub().
- *
- * Element IDs should look like an URL fragment identifier; for example, pass
- * "##foo" (hash <literal>foo</literal>) to get the geometry of the element that
- * has an <literal>id="foo"</literal> attribute.
- *
- * Returns: (transfer full) (nullable): a pixbuf, or %NULL if an error occurs
- * during rendering.
- *
- * Since: 2.14
- **/
-
-/**
- * rsvg_handle_get_pixbuf:
- * @handle: An #RsvgHandle
- *
- * Returns the pixbuf loaded by @handle.  The pixbuf returned will be reffed, so
- * the caller of this function must assume that ref.  If insufficient data has
- * been read to create the pixbuf, or an error occurred in loading, then %NULL
- * will be returned.  Note that the pixbuf may not be complete until
- * @rsvg_handle_close has been called.
- *
- * This function depends on the #RsvgHandle's DPI to compute dimensions in
- * pixels, so you should call rsvg_handle_set_dpi() beforehand.
- *
- * Returns: (transfer full) (nullable): the pixbuf loaded by @handle, or %NULL.
- **/
-
-/**
- * rsvg_handle_set_dpi:
- * @handle: An #RsvgHandle
- * @dpi: Dots Per Inch (i.e. as Pixels Per Inch)
- *
- * Sets the DPI at which the @handle will be rendered. Common values are
- * 75, 90, and 300 DPI.
- *
- * Passing a number <= 0 to @dpi will reset the DPI to whatever the default
- * value happens to be, but since rsvg_set_default_dpi() is deprecated, please
- * do not pass values <= 0 to this function.
- *
- * Since: 2.8
- */
-
-/**
- * rsvg_handle_set_dpi_x_y:
- * @handle: An #RsvgHandle
- * @dpi_x: Dots Per Inch (i.e. Pixels Per Inch)
- * @dpi_y: Dots Per Inch (i.e. Pixels Per Inch)
- *
- * Sets the DPI at which the @handle will be rendered. Common values are
- * 75, 90, and 300 DPI.
- *
- * Passing a number <= 0 to @dpi will reset the DPI to whatever the default
- * value happens to be, but since rsvg_set_default_dpi_x_y() is deprecated,
- * please do not pass values <= 0 to this function.
- *
- * Since: 2.8
- */
-
-/**
- * rsvg_handle_set_size_callback:
- * @handle: An #RsvgHandle
- * @size_func: (nullable): A sizing function, or %NULL
- * @user_data: User data to pass to @size_func, or %NULL
- * @user_data_destroy: Function to be called to destroy the data passed in @user_data,
- *   or %NULL.
- *
- * Sets the sizing function for the @handle, which can be used to override the
- * size that librsvg computes for SVG images.  The @size_func is called from the
- * following functions:
- *
- * <itemizedlist>
- *   <listitem>rsvg_handle_get_dimensions()</listitem>
- *   <listitem>rsvg_handle_get_dimensions_sub()</listitem>
- *   <listitem>rsvg_handle_get_position_sub()</listitem>
- *   <listitem>rsvg_handle_render_cairo()</listitem>
- *   <listitem>rsvg_handle_render_cairo_sub()</listitem>
- * </itemizedlist>
- *
- * Librsvg computes the size of the SVG being rendered, and passes it to the
- * @size_func, which may then modify these values to set the final size of the
- * generated image.
- *
- * Deprecated: 2.14.  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);
- * }
- * ]|
- *
- * This function was deprecated because when the @size_func is used, it makes it
- * unclear when the librsvg functions which call the @size_func will use the
- * size computed originally, or the callback-specified size, or whether it
- * refers to the whole SVG or to just a sub-element of it.  It is easier, and
- * unambiguous, to use code similar to the example above.
- **/
-
-/**
- * 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_document() 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">
- * ]|
- *
- * API ordering: This function must be called on a fully-loaded @handle.  See
- * the section <ulink url="#API-ordering">API ordering</ulink> for details.
- *
- * Panics: this function will panic if the @handle is not fully-loaded.
- *
- * Since: 2.46
- */
-
-/**
- * rsvg_handle_render_document:
- * @handle: An #RsvgHandle
- * @cr: A Cairo context
- * @viewport: Viewport size at which the whole SVG would be fitted.
- * @error: (optional): a location to store a #GError, or %NULL
- *
- * Renders the whole SVG document fitted to a viewport.
- *
- * The @viewport gives the position and size at which the whole SVG
- * document will be rendered.
- *
- * The @cr must be in a #CAIRO_STATUS_SUCCESS state, or this function will not
- * render anything, and instead will return an error.
- *
- * API ordering: This function must be called on a fully-loaded @handle.  See
- * the section <ulink url="#API-ordering">API ordering</ulink> for details.
- *
- * Panics: this function will panic if the @handle is not fully-loaded.
- *
- * Since: 2.46
- */
-
-/**
- * rsvg_handle_get_geometry_for_layer:
- * @handle: An #RsvgHandle
- * @id: (nullable): An element's id within the SVG, starting with "##" (a single
- * hash character), for example, "##layer1".  This notation corresponds to a
- * URL's fragment ID.  Alternatively, pass %NULL to compute the geometry for the
- * whole SVG.
- * @viewport: Viewport size at which the whole SVG would be fitted.
- * @out_ink_rect: (out)(optional): Place to store the ink rectangle of the element.
- * @out_logical_rect: (out)(optional): Place to store the logical rectangle of the element.
- * @error: (optional): a location to store a #GError, or %NULL
- *
- * Computes the ink rectangle and logical rectangle of an SVG element, or the
- * whole SVG, as if the whole SVG were rendered to a specific viewport.
- *
- * Element IDs should look like an URL fragment identifier; for example, pass
- * "##foo" (hash <literal>foo</literal>) to get the geometry of the element that
- * has an <literal>id="foo"</literal> attribute.
- *
- * The "ink rectangle" is the bounding box that would be painted
- * for fully- stroked and filled elements.
- *
- * The "logical rectangle" just takes into account the unstroked
- * paths and text outlines.
- *
- * Note that these bounds are not minimum bounds; for example,
- * clipping paths are not taken into account.
- *
- * You can pass #NULL for the @id if you want to measure all
- * the elements in the SVG, i.e. to measure everything from the
- * root element.
- *
- * This operation is not constant-time, as it involves going through all
- * the child elements.
- *
- * API ordering: This function must be called on a fully-loaded @handle.  See
- * the section <ulink url="#API-ordering">API ordering</ulink> for details.
- *
- * Panics: this function will panic if the @handle is not fully-loaded.
- *
- * Since: 2.46
- */
-
-/**
- * rsvg_handle_render_layer:
- * @handle: An #RsvgHandle
- * @cr: A Cairo context
- * @id: (nullable): An element's id within the SVG, starting with "##" (a single
- * hash character), for example, "##layer1".  This notation corresponds to a
- * URL's fragment ID.  Alternatively, pass %NULL to render the whole SVG document tree.
- * @viewport: Viewport size at which the whole SVG would be fitted.
- * @error: (optional): a location to store a #GError, or %NULL
- *
- * Renders a single SVG element in the same place as for a whole SVG document.
- *
- * This is equivalent to rsvg_handle_render_document(), but it renders only a
- * single element and its children, as if they composed an individual layer in
- * the SVG.  The element is rendered with the same transformation matrix as it
- * has within the whole SVG document.  Applications can use this to re-render a
- * single element and repaint it on top of a previously-rendered document, for
- * example.
- *
- * Element IDs should look like an URL fragment identifier; for example, pass
- * "##foo" (hash <literal>foo</literal>) to get the geometry of the element that
- * has an <literal>id="foo"</literal> attribute.
- *
- * You can pass #NULL for the @id if you want to render all
- * the elements in the SVG, i.e. to render everything from the
- * root element.
- *
- * API ordering: This function must be called on a fully-loaded @handle.  See
- * the section <ulink url="#API-ordering">API ordering</ulink> for details.
- *
- * Panics: this function will panic if the @handle is not fully-loaded.
- *
- * Since: 2.46
- */
-
-/**
- * rsvg_handle_get_geometry_for_element:
- * @handle: An #RsvgHandle
- * @id: (nullable): An element's id within the SVG, starting with "##" (a single
- * hash character), for example, "##layer1".  This notation corresponds to a
- * URL's fragment ID.  Alternatively, pass %NULL to compute the geometry for the
- * whole SVG.
- * @out_ink_rect: (out)(optional): Place to store the ink rectangle of the element.
- * @out_logical_rect: (out)(optional): Place to store the logical rectangle of the element.
- * @error: (optional): a location to store a #GError, or %NULL
- *
- * Computes the ink rectangle and logical rectangle of a single SVG element.
- *
- * While `rsvg_handle_get_geometry_for_layer` computes the geometry of an SVG element subtree with
- * its transformation matrix, this other function will compute the element's geometry
- * as if it were being rendered under an identity transformation by itself.  That is,
- * the resulting geometry is as if the element got extracted by itself from the SVG.
- *
- * This function is the counterpart to `rsvg_handle_render_element`.
- *
- * Element IDs should look like an URL fragment identifier; for example, pass
- * "##foo" (hash <literal>foo</literal>) to get the geometry of the element that
- * has an <literal>id="foo"</literal> attribute.
- *
- * The "ink rectangle" is the bounding box that would be painted
- * for fully- stroked and filled elements.
- *
- * The "logical rectangle" just takes into account the unstroked
- * paths and text outlines.
- *
- * Note that these bounds are not minimum bounds; for example,
- * clipping paths are not taken into account.
- *
- * You can pass #NULL for the @id if you want to measure all
- * the elements in the SVG, i.e. to measure everything from the
- * root element.
- *
- * This operation is not constant-time, as it involves going through all
- * the child elements.
- *
- * API ordering: This function must be called on a fully-loaded @handle.  See
- * the section <ulink url="#API-ordering">API ordering</ulink> for details.
- *
- * Panics: this function will panic if the @handle is not fully-loaded.
- *
- * Since: 2.46
- */
-
-/**
- * rsvg_handle_render_element:
- * @handle: An #RsvgHandle
- * @cr: A Cairo context
- * @id: (nullable): An element's id within the SVG, starting with "##" (a single
- * hash character), for example, "##layer1".  This notation corresponds to a
- * URL's fragment ID.  Alternatively, pass %NULL to render the whole SVG document tree.
- * @element_viewport: Viewport size in which to fit the element
- * @error: (optional): a location to store a #GError, or %NULL
- *
- * Renders a single SVG element to a given viewport
- *
- * This function can be used to extract individual element subtrees and render them,
- * scaled to a given @element_viewport.  This is useful for applications which have
- * reusable objects in an SVG and want to render them individually; for example, an
- * SVG full of icons that are meant to be be rendered independently of each other.
- *
- * Element IDs should look like an URL fragment identifier; for example, pass
- * "##foo" (hash <literal>foo</literal>) to get the geometry of the element that
- * has an <literal>id="foo"</literal> attribute.
- *
- * You can pass #NULL for the @id if you want to render all
- * the elements in the SVG, i.e. to render everything from the
- * root element.
- *
- * The `element_viewport` gives the position and size at which the named element will
- * be rendered.  FIXME: mention proportional scaling.
- *
- * API ordering: This function must be called on a fully-loaded @handle.  See
- * the section <ulink url="#API-ordering">API ordering</ulink> for details.
- *
- * Panics: this function will panic if the @handle is not fully-loaded.
- *
- * Since: 2.46
- */
-
-/**
- * rsvg_handle_internal_set_testing:
- * @handle: a #RsvgHandle
- * @testing: Whether to enable testing mode
- *
- * Do not call this function.  This is intended for librsvg's internal
- * test suite only.
- **/
diff --git a/librsvg/rsvg-pixbuf.c b/librsvg/rsvg-pixbuf.c
deleted file mode 100644
index 8b8e4d0f..00000000
--- a/librsvg/rsvg-pixbuf.c
+++ /dev/null
@@ -1,114 +0,0 @@
-/* -*- Mode: C; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
-/* vim: set sw=4 sts=4 expandtab: */
-/*
-   rsvg-file-util.c: SAX-based renderer for SVG files into a GdkPixbuf.
-
-   Copyright (C) 2000 Eazel, Inc.
-   Copyright (C) 2002 Dom Lachowicz <cinamod@hotmail.com>
-
-   This library is free software; you can redistribute it and/or
-   modify it under the terms of the GNU Lesser General Public
-   License as published by the Free Software Foundation; either
-   version 2.1 of the License, or (at your option) any later version.
-
-   This library 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
-   Lesser General Public License for more details.
-
-   You should have received a copy of the GNU Lesser General Public
-   License along with this library; if not, write to the Free Software
-   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
-
-   Author: Raph Levien <raph@artofcode.com>
-*/
-
-/**
- * SECTION: rsvg-pixbuf
- * @short_description: How to render SVGs into GdkPixbufs, for easy use in GTK+
- *  applications
- *
- * GdkPixbuf is a library for image loading and manipulation. It is part of the
- * cross-platform GTK+ widget toolkit.
- */
-
-/**
- * rsvg_pixbuf_from_file:
- * @filename: A file name
- * @error: return location for errors
- * 
- * Loads a new #GdkPixbuf from @filename and returns it.  The caller must
- * assume the reference to the reurned pixbuf. If an error occurred, @error is
- * set and %NULL is returned.
- * 
- * Return value: A newly allocated #GdkPixbuf, or %NULL
- * Deprecated: Set up a cairo matrix and use rsvg_handle_new_from_file() + rsvg_handle_render_cairo() instead.
- **/
-
-/**
- * rsvg_pixbuf_from_file_at_zoom:
- * @filename: A file name
- * @x_zoom: The horizontal zoom factor
- * @y_zoom: The vertical zoom factor
- * @error: return location for errors
- * 
- * Loads a new #GdkPixbuf from @filename and returns it.  This pixbuf is scaled
- * from the size indicated by the file by a factor of @x_zoom and @y_zoom.  The
- * caller must assume the reference to the returned pixbuf. If an error
- * occurred, @error is set and %NULL is returned.
- * 
- * Return value: A newly allocated #GdkPixbuf, or %NULL
- * Deprecated: Set up a cairo matrix and use rsvg_handle_new_from_file() + rsvg_handle_render_cairo() instead.
- **/
-
-/**
- * rsvg_pixbuf_from_file_at_zoom_with_max:
- * @filename: A file name
- * @x_zoom: The horizontal zoom factor
- * @y_zoom: The vertical zoom factor
- * @max_width: The requested max width
- * @max_height: The requested max height
- * @error: return location for errors
- * 
- * Loads a new #GdkPixbuf from @filename and returns it.  This pixbuf is scaled
- * from the size indicated by the file by a factor of @x_zoom and @y_zoom. If the
- * resulting pixbuf would be larger than max_width/max_heigh it is uniformly scaled
- * down to fit in that rectangle. The caller must assume the reference to the
- * returned pixbuf. If an error occurred, @error is set and %NULL is returned.
- * 
- * Return value: A newly allocated #GdkPixbuf, or %NULL
- * Deprecated: Set up a cairo matrix and use rsvg_handle_new_from_file() + rsvg_handle_render_cairo() instead.
- **/
-
-/**
- * rsvg_pixbuf_from_file_at_size:
- * @filename: A file name
- * @width: The new width, or -1
- * @height: The new height, or -1
- * @error: return location for errors
- * 
- * Loads a new #GdkPixbuf from @filename and returns it.  This pixbuf is scaled
- * from the size indicated to the new size indicated by @width and @height.  If
- * both of these are -1, then the default size of the image being loaded is
- * used.  The caller must assume the reference to the returned pixbuf. If an
- * error occurred, @error is set and %NULL is returned.
- * 
- * Return value: A newly allocated #GdkPixbuf, or %NULL
- * Deprecated: Set up a cairo matrix and use rsvg_handle_new_from_file() + rsvg_handle_render_cairo() instead.
- **/
-
-/**
- * rsvg_pixbuf_from_file_at_max_size:
- * @filename: A file name
- * @max_width: The requested max width
- * @max_height: The requested max height
- * @error: return location for errors
- * 
- * Loads a new #GdkPixbuf from @filename and returns it.  This pixbuf is uniformly
- * scaled so that the it fits into a rectangle of size max_width * max_height. The
- * caller must assume the reference to the returned pixbuf. If an error occurred,
- * @error is set and %NULL is returned.
- * 
- * Return value: A newly allocated #GdkPixbuf, or %NULL
- * Deprecated: Set up a cairo matrix and use rsvg_handle_new_from_file() + rsvg_handle_render_cairo() instead.
- **/
diff --git a/librsvg/rsvg.h b/librsvg/rsvg.h
index 2b863768..6432df67 100644
--- a/librsvg/rsvg.h
+++ b/librsvg/rsvg.h
@@ -52,16 +52,6 @@ G_BEGIN_DECLS
 
 #endif /* __GTK_DOC_IGNORE__ */
 
-#define RSVG_TYPE_HANDLE                  (rsvg_handle_get_type ())
-#define RSVG_HANDLE(obj)                  (G_TYPE_CHECK_INSTANCE_CAST ((obj), RSVG_TYPE_HANDLE, RsvgHandle))
-#define RSVG_HANDLE_CLASS(klass)          (G_TYPE_CHECK_CLASS_CAST ((klass), RSVG_TYPE_HANDLE, RsvgHandleClass))
-#define RSVG_IS_HANDLE(obj)               (G_TYPE_CHECK_INSTANCE_TYPE ((obj), RSVG_TYPE_HANDLE))
-#define RSVG_IS_HANDLE_CLASS(klass)       (G_TYPE_CHECK_CLASS_TYPE ((klass), RSVG_TYPE_HANDLE))
-#define RSVG_HANDLE_GET_CLASS(obj)        (G_TYPE_INSTANCE_GET_CLASS ((obj), RSVG_TYPE_HANDLE, RsvgHandleClass))
-
-RSVG_API
-GType rsvg_handle_get_type (void);
-
 /**
  * RsvgError:
  * @RSVG_ERROR_FAILED: the request failed
@@ -73,6 +63,14 @@ typedef enum {
 } RsvgError;
 
 #define RSVG_ERROR (rsvg_error_quark ())
+
+/**
+ * rsvg_error_quark:
+ *
+ * The error domain for RSVG
+ *
+ * Returns: The error domain
+ */
 RSVG_API
 GQuark rsvg_error_quark (void) G_GNUC_CONST;
 
@@ -80,6 +78,307 @@ RSVG_API
 GType rsvg_error_get_type (void);
 #define RSVG_TYPE_ERROR (rsvg_error_get_type())
 
+/**
+ * SECTION: rsvg-handle
+ * @short_description: Loads SVG data into memory.
+ *
+ * This is the main entry point into the librsvg library.  An RsvgHandle is an
+ * object that represents SVG data in memory.  Your program creates an
+ * RsvgHandle from an SVG file, or from a memory buffer that contains SVG data,
+ * or in the most general form, from a #GInputStream that will provide SVG data.
+ *
+ * Librsvg can load SVG images and render them to Cairo surfaces,
+ * using a mixture of SVG's [static mode] and [secure static mode].
+ * Librsvg does not do animation nor scripting, and can load
+ * references to external data only in some situations; see below.
+ *
+ * Librsvg supports reading <ulink
+ * url="https://www.w3.org/TR/SVG11/">SVG 1.1</ulink> data, and is
+ * gradually adding support for features in <ulink
+ * url="https://www.w3.org/TR/SVG2/">SVG 2</ulink>.  Librsvg also supports
+ * SVGZ files, which are just an SVG stream compressed with the GZIP algorithm.
+ *
+ * # The "base file" and resolving references to external files
+ *
+ * When you load an SVG, librsvg needs to know the location of the "base file"
+ * for it.  This is so that librsvg can determine the location of referenced
+ * entities.  For example, say you have an SVG in <filename>/foo/bar/foo.svg</filename>
+ * and that it has an image element like this:
+ *
+ * |[
+ * <image href="resources/foo.png" .../>
+ * ]|
+ *
+ * In this case, librsvg needs to know the location of the toplevel
+ * <filename>/foo/bar/foo.svg</filename> so that it can generate the appropriate
+ * reference to <filename>/foo/bar/resources/foo.png</filename>.
+ *
+ * ## Security and locations of referenced files
+ *
+ * When processing an SVG, librsvg will only load referenced files if they are
+ * in the same directory as the base file, or in a subdirectory of it.  That is,
+ * if the base file is <filename>/foo/bar/baz.svg</filename>, then librsvg will
+ * only try to load referenced files (from SVG's
+ * <literal>&lt;image&gt;</literal> element, for example, or from content
+ * included through XML entities) if those files are in <filename>/foo/bar/<!--
+ * -->*</filename> or in <filename>/foo/bar/<!-- -->*<!-- -->/.../<!--
+ * -->*</filename>.  This is so that malicious SVG files cannot include files
+ * that are in a directory above.
+ *
+ * The full set of rules for deciding which URLs may be loaded is as follows;
+ * they are applied in order.  A referenced URL will not be loaded as soon as
+ * one of these rules fails:
+ *
+ * <orderedlist>
+ *   <listitem>
+ *     All <literal>data:</literal> URLs may be loaded.  These are sometimes used
+ *     to include raster image data, encoded as base-64, directly in an SVG file.
+ *   </listitem>
+ *
+ *   <listitem>
+ *     All other URL schemes in references require a base URL.  For
+ *     example, this means that if you load an SVG with
+ *     rsvg_handle_new_from_data() without calling rsvg_handle_set_base_uri(),
+ *     then any referenced files will not be allowed (e.g. raster images to be
+ *     loaded from other files will not work).
+ *   </listitem>
+ *
+ *   <listitem>
+ *     If referenced URLs are absolute, rather than relative, then they must
+ *     have the same scheme as the base URL.  For example, if the base URL has a
+ *     "<literal>file</literal>" scheme, then all URL references inside the SVG must
+ *     also have the "<literal>file</literal>" scheme, or be relative references which
+ *     will be resolved against the base URL.
+ *   </listitem>
+ *
+ *   <listitem>
+ *     If referenced URLs have a "<literal>resource</literal>" scheme, that is,
+ *     if they are included into your binary program with GLib's resource
+ *     mechanism, they are allowed to be loaded (provided that the base URL is
+ *     also a "<literal>resource</literal>", per the previous rule).
+ *   </listitem>
+ *
+ *   <listitem>
+ *     Otherwise, non-<literal>file</literal> schemes are not allowed.  For
+ *     example, librsvg will not load <literal>http</literal> resources, to keep
+ *     malicious SVG data from "phoning home".
+ *   </listitem>
+ *
+ *   <listitem>
+ *     A relative URL must resolve to the same directory as the base URL, or to
+ *     one of its subdirectories.  Librsvg will canonicalize filenames, by
+ *     removing ".." path components and resolving symbolic links, to decide whether
+ *     files meet these conditions.
+ *   </listitem>
+ * </orderedlist>
+ *
+ * # Loading an SVG with GIO
+ *
+ * This is the easiest and most resource-efficient way of loading SVG data into
+ * an #RsvgHandle.
+ *
+ * If you have a #GFile that stands for an SVG file, you can simply call
+ * rsvg_handle_new_from_gfile_sync() to load an RsvgHandle from it.
+ *
+ * Alternatively, if you have a #GInputStream, you can use
+ * rsvg_handle_new_from_stream_sync().
+ *
+ * Both of those methods allow specifying a #GCancellable, so the loading
+ * process can be cancelled from another thread.
+ *
+ * ## Loading an SVG from memory
+ *
+ * If you already have SVG data in a byte buffer in memory, you can create a
+ * memory input stream with g_memory_input_stream_new_from_data() and feed that
+ * to rsvg_handle_new_from_stream_sync().
+ *
+ * Note that in this case, it is important that you specify the base_file for
+ * the in-memory SVG data.  Librsvg uses the base_file to resolve links to
+ * external content, like raster images.
+ *
+ * # Loading an SVG without GIO
+ *
+ * You can load an RsvgHandle from a simple filename or URI with
+ * rsvg_handle_new_from_file().  Note that this is a blocking operation; there
+ * is no way to cancel it if loading a remote URI takes a long time.  Also, note that
+ * this method does not let you specify #RsvgHandleFlags.
+ *
+ * Otherwise, loading an SVG without GIO is not recommended, since librsvg will
+ * need to buffer your entire data internally before actually being able to
+ * parse it.  The deprecated way of doing this is by creating a handle with
+ * rsvg_handle_new() or rsvg_handle_new_with_flags(), and then using
+ * rsvg_handle_write() and rsvg_handle_close() to feed the handle with SVG data.
+ * Still, please try to use the GIO stream functions instead.
+ *
+ * # Resolution of the rendered image (dots per inch, or DPI)
+ *
+ * SVG images can contain dimensions like "<literal>5 cm</literal>" or
+ * "<literal>2 pt</literal>" that must be converted from physical units into
+ * device units.  To do this, librsvg needs to know the actual dots per inch
+ * (DPI) of your target device.  You can call rsvg_handle_set_dpi() or
+ * rsvg_handle_set_dpi_x_y() on an RsvgHandle to set the DPI before rendering
+ * it.
+ *
+ * # Rendering
+ *
+ * The preferred way to render an already-loaded RsvgHandle is to use
+ * rsvg_handle_render_cairo().  Please see its documentation for details.
+ *
+ * Alternatively, you can use rsvg_handle_get_pixbuf() to directly obtain a
+ * #GdkPixbuf with the rendered image.  This is simple, but it does not let you
+ * control the size at which the SVG will be rendered.  It will just be rendered
+ * at the size which rsvg_handle_get_dimensions() would return, which depends on
+ * the dimensions that librsvg is able to compute from the SVG data.
+ *
+ * # API ordering
+ *
+ * Due to the way the librsvg API evolved over time, an #RsvgHandle object is available
+ * for use as soon as it is constructed.  However, not all of its methods can be
+ * called at any time.  For example, an #RsvgHandle just constructed with rsvg_handle_new()
+ * is not loaded yet, and it does not make sense to call rsvg_handle_get_dimensions() on it
+ * just at that point.
+ *
+ * The documentation for the available methods in #RsvgHandle may mention that a particular
+ * method is only callable on a "fully loaded handle".  This means either:
+ *
+ * <itemizedlist>
+ *   <listitem>
+ *     The handle was loaded with rsvg_handle_write() and rsvg_handle_close(), and
+ *     those functions returned no errors.
+ *   </listitem>
+ *   <listitem>
+ *     The handle was loaded with rsvg_handle_read_stream_sync() and that function
+ *     returned no errors.
+ *   </listitem>
+ * </itemizedlist>
+ *
+ * Before librsvg 2.46, the library did not fully verify that a handle was in a
+ * fully loaded state for the methods that require it.  To preserve
+ * compatibility with old code which inadvertently called the API without
+ * checking for errors, or which called some methods outside of the expected
+ * order, librsvg will just emit a g_critical() message in those cases.
+ *
+ * New methods introduced in librsvg 2.46 and later will check for the correct
+ * ordering, and panic if they are called out of order.  This will abort
+ * the program as if it had a failed assertion.
+ */
+
+/***** Begin documentation for RsvgHandle properties *****/
+
+/**
+ * RsvgHandle:flags:
+ *
+ * Flags from #RsvgHandleFlags.
+ *
+ * Since: 2.36
+ */
+
+/**
+ * RsvgHandle::dpi-x:
+ *
+ * Horizontal resolution in dots per inch.
+ */
+
+/**
+ * RsvgHandle::dpi-y:
+ *
+ * Horizontal resolution in dots per inch.
+ */
+
+/**
+ * RsvgHandle::base-uri:
+ *
+ * Base URI, to be used to resolve relative references for resources.  See the section
+ */
+
+/**
+ * RsvgHandle:width:
+ *
+ * Width, in pixels, of the rendered SVG after calling the size callback
+ * as specified by rsvg_handle_set_size_callback().
+ *
+ * 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.
+ */
+
+/**
+ * RsvgHandle:height:
+ *
+ * Height, in pixels, of the rendered SVG after calling the size callback
+ * as specified by rsvg_handle_set_size_callback().
+ *
+ * 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.
+ */
+
+/**
+ * RsvgHandle:em:
+ *
+ * Exact width, in pixels, of the rendered SVG before calling the size callback
+ * as specified by rsvg_handle_set_size_callback().
+ *
+ * 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.
+ */
+
+/**
+ * RsvgHandle:ex:
+ *
+ * Exact height, in pixels, of the rendered SVG before calling the size callback
+ * as specified by rsvg_handle_set_size_callback().
+ *
+ * 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.
+ */
+
+/**
+ * RsvgHandle:title:
+ *
+ * SVG's title.
+ *
+ * Deprecated: 2.36.  Reading this property always returns #NULL.
+ */
+
+/**
+ * RsvgHandle:desc:
+ *
+ * SVG's description.
+ *
+ * Deprecated: 2.36.  Reading this property always returns #NULL.
+ */
+
+/**
+ * RsvgHandle:metadata:
+ *
+ * SVG's metadata
+ *
+ * Deprecated: 2.36.  Reading this property always returns #NULL.
+ */
+
+/***** End documentation for RsvgHandle properties *****/
+
+#define RSVG_TYPE_HANDLE                  (rsvg_handle_get_type ())
+#define RSVG_HANDLE(obj)                  (G_TYPE_CHECK_INSTANCE_CAST ((obj), RSVG_TYPE_HANDLE, RsvgHandle))
+#define RSVG_HANDLE_CLASS(klass)          (G_TYPE_CHECK_CLASS_CAST ((klass), RSVG_TYPE_HANDLE, RsvgHandleClass))
+#define RSVG_IS_HANDLE(obj)               (G_TYPE_CHECK_INSTANCE_TYPE ((obj), RSVG_TYPE_HANDLE))
+#define RSVG_IS_HANDLE_CLASS(klass)       (G_TYPE_CHECK_CLASS_TYPE ((klass), RSVG_TYPE_HANDLE))
+#define RSVG_HANDLE_GET_CLASS(obj)        (G_TYPE_INSTANCE_GET_CLASS ((obj), RSVG_TYPE_HANDLE, RsvgHandleClass))
+
+RSVG_API
+GType rsvg_handle_get_type (void);
+
 typedef struct _RsvgHandle RsvgHandle;
 typedef struct _RsvgHandleClass RsvgHandleClass;
 typedef struct _RsvgDimensionData RsvgDimensionData;
@@ -165,55 +464,328 @@ struct _RsvgRectangle {
     double height;
 };
 
-
+/**
+ * rsvg_cleanup:
+ *
+ * Since: 2.36
+ * Deprecated: 2.46: No-op. This function should not be called from normal programs.
+ */
 RSVG_DEPRECATED
 void rsvg_cleanup (void);
 
+/**
+ * rsvg_set_default_dpi:
+ * @dpi: Dots Per Inch (aka Pixels Per Inch)
+ *
+ * Do not use this function.  Create an #RsvgHandle and call
+ * rsvg_handle_set_dpi() on it instead.
+ *
+ * Since: 2.8
+ *
+ * Deprecated: 2.42.3: This function used to set a global default DPI.  However,
+ * it only worked if it was called before any #RsvgHandle objects had been
+ * created; it would not work after that.  To avoid global mutable state, please
+ * use rsvg_handle_set_dpi() instead.
+ */
 RSVG_DEPRECATED
-void rsvg_set_default_dpi	(double dpi);
+void rsvg_set_default_dpi (double dpi);
 
+/**
+ * rsvg_set_default_dpi_x_y:
+ * @dpi_x: Dots Per Inch (aka Pixels Per Inch)
+ * @dpi_y: Dots Per Inch (aka Pixels Per Inch)
+ *
+ * Do not use this function.  Create an #RsvgHandle and call
+ * rsvg_handle_set_dpi_x_y() on it instead.
+ *
+ * Since: 2.8
+ *
+ * Deprecated: 2.42.3: This function used to set a global default DPI.  However,
+ * it only worked if it was called before any #RsvgHandle objects had been
+ * created; it would not work after that.  To avoid global mutable state, please
+ * use rsvg_handle_set_dpi() instead.
+ */
 RSVG_DEPRECATED
-void rsvg_set_default_dpi_x_y	(double dpi_x, double dpi_y);
+void rsvg_set_default_dpi_x_y (double dpi_x, double dpi_y);
 
+/**
+ * rsvg_handle_set_dpi:
+ * @handle: An #RsvgHandle
+ * @dpi: Dots Per Inch (i.e. as Pixels Per Inch)
+ *
+ * Sets the DPI at which the @handle will be rendered. Common values are
+ * 75, 90, and 300 DPI.
+ *
+ * Passing a number <= 0 to @dpi will reset the DPI to whatever the default
+ * value happens to be, but since rsvg_set_default_dpi() is deprecated, please
+ * do not pass values <= 0 to this function.
+ *
+ * Since: 2.8
+ */
 RSVG_API
-void rsvg_handle_set_dpi	(RsvgHandle *handle, double dpi);
+void rsvg_handle_set_dpi (RsvgHandle *handle, double dpi);
+
+/**
+ * rsvg_handle_set_dpi_x_y:
+ * @handle: An #RsvgHandle
+ * @dpi_x: Dots Per Inch (i.e. Pixels Per Inch)
+ * @dpi_y: Dots Per Inch (i.e. Pixels Per Inch)
+ *
+ * Sets the DPI at which the @handle will be rendered. Common values are
+ * 75, 90, and 300 DPI.
+ *
+ * Passing a number <= 0 to @dpi will reset the DPI to whatever the default
+ * value happens to be, but since rsvg_set_default_dpi_x_y() is deprecated,
+ * please do not pass values <= 0 to this function.
+ *
+ * Since: 2.8
+ */
 RSVG_API
-void rsvg_handle_set_dpi_x_y	(RsvgHandle *handle, double dpi_x, double dpi_y);
+void rsvg_handle_set_dpi_x_y (RsvgHandle *handle, double dpi_x, double dpi_y);
 
+/**
+ * rsvg_handle_new:
+ *
+ * Returns a new rsvg handle.  Must be freed with @g_object_unref.  This
+ * handle can be used to load an image.
+ *
+ * The preferred way of loading SVG data into the returned #RsvgHandle is with
+ * rsvg_handle_read_stream_sync().
+ *
+ * The deprecated way of loading SVG data is with rsvg_handle_write() and
+ * rsvg_handle_close(); note that these require buffering the entire file
+ * internally, and for this reason it is better to use the stream functions:
+ * rsvg_handle_new_from_stream_sync(), rsvg_handle_read_stream_sync(), or
+ * rsvg_handle_new_from_gfile_sync().
+ *
+ * After loading the #RsvgHandle with data, you can render it using Cairo or get
+ * a GdkPixbuf from it. When finished, free the handle with g_object_unref(). No
+ * more than one image can be loaded with one handle.
+ *
+ * Note that this function creates an #RsvgHandle with no flags set.  If you
+ * require any of #RsvgHandleFlags to be set, use any of
+ * rsvg_handle_new_with_flags(), rsvg_handle_new_from_stream_sync(), or
+ * rsvg_handle_new_from_gfile_sync().
+ *
+ * Returns: A new #RsvgHandle with no flags set.
+ **/
 RSVG_API
-RsvgHandle  *rsvg_handle_new		(void);
+RsvgHandle *rsvg_handle_new (void);
 
+/**
+ * rsvg_handle_write:
+ * @handle: an #RsvgHandle
+ * @buf: (array length=count) (element-type guchar): pointer to svg data
+ * @count: length of the @buf buffer in bytes
+ * @error: (optional): a location to store a #GError, or %NULL
+ *
+ * Loads the next @count bytes of the image.
+ *
+ * Before calling this function for the first time, you may need to call
+ * rsvg_handle_set_base_uri() or rsvg_handle_set_base_gfile() to set the "base
+ * file" for resolving references to external resources.  SVG elements like
+ * <literal>&lt;image&gt;</literal> which reference external resources will be
+ * resolved relative to the location you specify with those functions.
+ *
+ * Returns: %TRUE on success, or %FALSE on error.
+ *
+ * Deprecated: 2.46.  Use rsvg_handle_read_stream_sync() or the constructor
+ * functions rsvg_handle_new_from_gfile_sync() or
+ * rsvg_handle_new_from_stream_sync().  This function is deprecated because it
+ * will accumulate data from the @buf in memory until rsvg_handle_close() gets
+ * called.  To avoid a big temporary buffer, use the suggested functions, which
+ * take a #GFile or a #GInputStream and do not require a temporary buffer.
+ **/
 RSVG_DEPRECATED_FOR(rsvg_handle_read_stream_sync)
-gboolean     rsvg_handle_write		(RsvgHandle   *handle,
-                                         const guchar *buf,
-                                         gsize         count,
-                                         GError      **error);
+gboolean rsvg_handle_write (RsvgHandle   *handle,
+                            const guchar *buf,
+                            gsize         count,
+                            GError      **error);
+
+/**
+ * rsvg_handle_close:
+ * @handle: a #RsvgHandle
+ * @error: (optional): a location to store a #GError, or %NULL
+ *
+ * Closes @handle, to indicate that loading the image is complete.  This will
+ * return %TRUE if the loader closed successfully and the SVG data was parsed
+ * correctly.  Note that @handle isn't freed until @g_object_unref is called.
+ *
+ * Returns: %TRUE on success, or %FALSE on error.
+ *
+ * Deprecated: 2.46.  Use rsvg_handle_read_stream_sync() or the constructor
+ * functions rsvg_handle_new_from_gfile_sync() or
+ * rsvg_handle_new_from_stream_sync().  See the deprecation notes for
+ * rsvg_handle_write() for more information.
+ **/
 RSVG_DEPRECATED_FOR(rsvg_handle_read_stream_sync)
-gboolean     rsvg_handle_close		(RsvgHandle *handle, GError **error);
+gboolean rsvg_handle_close (RsvgHandle *handle, GError **error);
 
+/**
+ * rsvg_handle_get_pixbuf:
+ * @handle: An #RsvgHandle
+ *
+ * Returns the pixbuf loaded by @handle.  The pixbuf returned will be reffed, so
+ * the caller of this function must assume that ref.  If insufficient data has
+ * been read to create the pixbuf, or an error occurred in loading, then %NULL
+ * will be returned.  Note that the pixbuf may not be complete until
+ * @rsvg_handle_close has been called.
+ *
+ * This function depends on the #RsvgHandle's DPI to compute dimensions in
+ * pixels, so you should call rsvg_handle_set_dpi() beforehand.
+ *
+ * Returns: (transfer full) (nullable): the pixbuf loaded by @handle, or %NULL.
+ **/
 RSVG_API
-GdkPixbuf   *rsvg_handle_get_pixbuf	(RsvgHandle *handle);
+GdkPixbuf *rsvg_handle_get_pixbuf (RsvgHandle *handle);
+
+/**
+ * rsvg_handle_get_pixbuf_sub:
+ * @handle: An #RsvgHandle
+ * @id: (nullable): An element's id within the SVG, starting with "##" (a single
+ * hash character), for example, "##layer1".  This notation corresponds to a
+ * URL's fragment ID.  Alternatively, pass %NULL to use the whole SVG.
+ *
+ * Creates a #GdkPixbuf the same size as the entire SVG loaded into @handle, but
+ * only renders the sub-element that has the specified @id (and all its
+ * sub-sub-elements recursively).  If @id is #NULL, this function renders the
+ * whole SVG.
+ *
+ * This function depends on the #RsvgHandle's DPI to compute dimensions in
+ * pixels, so you should call rsvg_handle_set_dpi() beforehand.
+ *
+ * If you need to render an image which is only big enough to fit a particular
+ * sub-element of the SVG, consider using rsvg_handle_render_cairo_sub(), upon a
+ * surface that is just the size returned by rsvg_handle_get_dimensions_sub().
+ * You will need to offset the rendering by the amount returned in
+ * rsvg_handle_get_position_sub().
+ *
+ * Element IDs should look like an URL fragment identifier; for example, pass
+ * "##foo" (hash <literal>foo</literal>) to get the geometry of the element that
+ * has an <literal>id="foo"</literal> attribute.
+ *
+ * Returns: (transfer full) (nullable): a pixbuf, or %NULL if an error occurs
+ * during rendering.
+ *
+ * Since: 2.14
+ **/
 RSVG_API
-GdkPixbuf   *rsvg_handle_get_pixbuf_sub (RsvgHandle *handle, const char *id);
+GdkPixbuf *rsvg_handle_get_pixbuf_sub (RsvgHandle *handle, const char *id);
 
+/**
+ * rsvg_handle_get_base_uri:
+ * @handle: A #RsvgHandle
+ *
+ * Gets the base uri for this #RsvgHandle.
+ *
+ * Returns: the base uri, possibly null
+ * Since: 2.8
+ */
 RSVG_API
-const char  *rsvg_handle_get_base_uri (RsvgHandle *handle);
+const char *rsvg_handle_get_base_uri (RsvgHandle *handle);
+
+/**
+ * rsvg_handle_set_base_uri:
+ * @handle: A #RsvgHandle
+ * @base_uri: The base uri
+ *
+ * Set the base URI for this SVG.
+ *
+ * Note: This function may only be called before rsvg_handle_write() or
+ * rsvg_handle_read_stream_sync() have been called.
+ *
+ * Since: 2.9
+ */
 RSVG_API
-void         rsvg_handle_set_base_uri (RsvgHandle *handle, const char *base_uri);
+void rsvg_handle_set_base_uri (RsvgHandle *handle, const char *base_uri);
 
+/**
+ * rsvg_handle_get_dimensions:
+ * @handle: A #RsvgHandle
+ * @dimension_data: (out): A place to store the SVG's size
+ *
+ * Get the SVG's size. Do not call from within the size_func callback, because
+ * an infinite loop will occur.
+ *
+ * This function depends on the #RsvgHandle's DPI to compute dimensions in
+ * pixels, so you should call rsvg_handle_set_dpi() beforehand.
+ *
+ * Since: 2.14
+ */
 RSVG_API
 void rsvg_handle_get_dimensions (RsvgHandle *handle, RsvgDimensionData *dimension_data);
 
+/**
+ * rsvg_handle_get_dimensions_sub:
+ * @handle: A #RsvgHandle
+ * @dimension_data: (out): A place to store the SVG's size
+ * @id: (nullable): An element's id within the SVG, starting with "##" (a single
+ * hash character), for example, "##layer1".  This notation corresponds to a
+ * URL's fragment ID.  Alternatively, pass %NULL to use the whole SVG.
+ *
+ * Get the size of a subelement of the SVG file. Do not call from within the
+ * size_func callback, because an infinite loop will occur.
+ *
+ * This function depends on the #RsvgHandle's DPI to compute dimensions in
+ * pixels, so you should call rsvg_handle_set_dpi() beforehand.
+ *
+ * Element IDs should look like an URL fragment identifier; for example, pass
+ * "##foo" (hash <literal>foo</literal>) to get the geometry of the element that
+ * has an <literal>id="foo"</literal> attribute.
+ *
+ * Deprecated: 2.46.  Use rsvg_handle_get_geometry_for_layer() instead.
+ *
+ * Since: 2.22
+ */
 RSVG_DEPRECATED_FOR(rsvg_handle_get_geometry_for_layer)
 gboolean rsvg_handle_get_dimensions_sub (RsvgHandle        *handle,
                                          RsvgDimensionData *dimension_data,
                                          const char        *id);
 
+/**
+ * rsvg_handle_get_position_sub:
+ * @handle: A #RsvgHandle
+ * @position_data: (out): A place to store the SVG fragment's position.
+ * @id: (nullable): An element's id within the SVG, starting with "##" (a single
+ * hash character), for example, "##layer1".  This notation corresponds to a
+ * URL's fragment ID.  Alternatively, pass %NULL to use the whole SVG.
+ *
+ * Get the position of a subelement of the SVG file. Do not call from within
+ * the size_func callback, because an infinite loop will occur.
+ *
+ * This function depends on the #RsvgHandle's DPI to compute dimensions in
+ * pixels, so you should call rsvg_handle_set_dpi() beforehand.
+ *
+ * Element IDs should look like an URL fragment identifier; for example, pass
+ * "##foo" (hash <literal>foo</literal>) to get the geometry of the element that
+ * has an <literal>id="foo"</literal> attribute.
+ *
+ * Deprecated: 2.46.  Use rsvg_handle_get_geometry_for_layer() instead.
+ *
+ * Since: 2.22
+ */
 RSVG_DEPRECATED_FOR(rsvg_handle_get_geometry_for_layer)
 gboolean rsvg_handle_get_position_sub (RsvgHandle       *handle,
                                        RsvgPositionData *position_data,
                                        const char       *id);
 
+/**
+ * rsvg_handle_has_sub:
+ * @handle: a #RsvgHandle
+ * @id: An element's id within the SVG, starting with "##" (a single hash
+ * character), for example, "##layer1".  This notation corresponds to a URL's
+ * fragment ID.
+ *
+ * Checks whether the element @id exists in the SVG document.
+ *
+ * Element IDs should look like an URL fragment identifier; for example, pass
+ * "##foo" (hash <literal>foo</literal>) to get the geometry of the element that
+ * has an <literal>id="foo"</literal> attribute.
+ *
+ * Returns: %TRUE if @id exists in the SVG document, %FALSE otherwise.
+ *
+ * Since: 2.22
+ */
 RSVG_API
 gboolean rsvg_handle_has_sub (RsvgHandle *handle, const char *id);
 
@@ -269,6 +841,50 @@ typedef struct {
     RsvgUnit unit;
 } RsvgLength;
 
+/**
+ * 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_document() 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">
+ * ]|
+ *
+ * API ordering: This function must be called on a fully-loaded @handle.  See
+ * the section <ulink url="#API-ordering">API ordering</ulink> for details.
+ *
+ * Panics: this function will panic if the @handle is not fully-loaded.
+ *
+ * Since: 2.46
+ */
 RSVG_API
 void rsvg_handle_get_intrinsic_dimensions (RsvgHandle *handle,
                                            gboolean   *out_has_width,
@@ -312,25 +928,119 @@ RSVG_API
 GType rsvg_handle_flags_get_type (void);
 #define RSVG_TYPE_HANDLE_FLAGS (rsvg_handle_flags_get_type())
 
+/**
+ * rsvg_handle_new_with_flags:
+ * @flags: flags from #RsvgHandleFlags
+ *
+ * Creates a new #RsvgHandle with flags @flags.  After calling this function,
+ * you can feed the resulting handle with SVG data by using
+ * rsvg_handle_read_stream_sync().
+ *
+ * Returns: (transfer full): a new #RsvgHandle
+ *
+ * Since: 2.36
+ **/
 RSVG_API
 RsvgHandle *rsvg_handle_new_with_flags (RsvgHandleFlags flags);
 
+/**
+ * rsvg_handle_set_base_gfile:
+ * @handle: a #RsvgHandle
+ * @base_file: a #GFile
+ *
+ * Set the base URI for @handle from @file.
+ *
+ * Note: This function may only be called before rsvg_handle_write() or
+ * rsvg_handle_read_stream_sync() have been called.
+ *
+ * Since: 2.32
+ */
 RSVG_API
-void        rsvg_handle_set_base_gfile (RsvgHandle *handle,
-                                        GFile      *base_file);
+void rsvg_handle_set_base_gfile (RsvgHandle *handle,
+                                 GFile      *base_file);
 
+/**
+ * rsvg_handle_read_stream_sync:
+ * @handle: a #RsvgHandle
+ * @stream: a #GInputStream
+ * @cancellable: (nullable): a #GCancellable, or %NULL
+ * @error: (optional): a location to store a #GError, or %NULL
+ *
+ * Reads @stream and writes the data from it to @handle.
+ *
+ * Before calling this function, you may need to call rsvg_handle_set_base_uri()
+ * or rsvg_handle_set_base_gfile() to set the "base file" for resolving
+ * references to external resources.  SVG elements like
+ * <literal>&lt;image&gt;</literal> which reference external resources will be
+ * resolved relative to the location you specify with those functions.
+ *
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the
+ * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
+ * returned.
+ *
+ * Returns: %TRUE if reading @stream succeeded, or %FALSE otherwise
+ *   with @error filled in
+ *
+ * Since: 2.32
+ */
 RSVG_API
-gboolean    rsvg_handle_read_stream_sync (RsvgHandle   *handle,
-                                          GInputStream *stream,
-                                          GCancellable *cancellable,
-                                          GError      **error);
+gboolean rsvg_handle_read_stream_sync (RsvgHandle   *handle,
+                                       GInputStream *stream,
+                                       GCancellable *cancellable,
+                                       GError      **error);
 
+/**
+ * rsvg_handle_new_from_gfile_sync:
+ * @file: a #GFile
+ * @flags: flags from #RsvgHandleFlags
+ * @cancellable: (nullable): a #GCancellable, or %NULL
+ * @error: (optional): a location to store a #GError, or %NULL
+ *
+ * Creates a new #RsvgHandle for @file.
+ *
+ * This function sets the "base file" of the handle to be @file itself, so SVG
+ * elements like <literal>&lt;image&gt;</literal> which reference external
+ * resources will be resolved relative to the location of @file.
+ *
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the
+ * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
+ * returned in @error.
+ *
+ * Returns: a new #RsvgHandle on success, or %NULL with @error filled in
+ *
+ * Since: 2.32
+ */
 RSVG_API
 RsvgHandle *rsvg_handle_new_from_gfile_sync (GFile          *file,
                                              RsvgHandleFlags flags,
                                              GCancellable   *cancellable,
                                              GError        **error);
 
+/**
+ * rsvg_handle_new_from_stream_sync:
+ * @input_stream: a #GInputStream
+ * @base_file: (nullable): a #GFile, or %NULL
+ * @flags: flags from #RsvgHandleFlags
+ * @cancellable: (nullable): a #GCancellable, or %NULL
+ * @error: (optional): a location to store a #GError, or %NULL
+ *
+ * Creates a new #RsvgHandle for @stream.
+ *
+ * This function sets the "base file" of the handle to be @base_file if
+ * provided.  SVG elements like <literal>&lt;image&gt;</literal> which reference
+ * external resources will be resolved relative to the location of @base_file.
+ *
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the
+ * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
+ * returned in @error.
+ *
+ * Returns: a new #RsvgHandle on success, or %NULL with @error filled in
+ *
+ * Since: 2.32
+ */
 RSVG_API
 RsvgHandle *rsvg_handle_new_from_stream_sync (GInputStream   *input_stream,
                                               GFile          *base_file,
@@ -338,11 +1048,60 @@ RsvgHandle *rsvg_handle_new_from_stream_sync (GInputStream   *input_stream,
                                               GCancellable   *cancellable,
                                               GError        **error);
 
+/**
+ * rsvg_handle_new_from_data:
+ * @data: (array length=data_len): The SVG data
+ * @data_len: The length of @data, in bytes
+ * @error: (optional): return location for errors
+ *
+ * Loads the SVG specified by @data.  Note that this function creates an
+ * #RsvgHandle without a base URL, and without any #RsvgHandleFlags.  If you
+ * need these, use rsvg_handle_new_from_stream_sync() instead by creating
+ * a #GMemoryInputStream from your data.
+ *
+ * Returns: A #RsvgHandle or %NULL if an error occurs.
+ * Since: 2.14
+ */
 RSVG_API
 RsvgHandle *rsvg_handle_new_from_data (const guint8 *data, gsize data_len, GError **error);
+
+/**
+ * rsvg_handle_new_from_file:
+ * @filename: The file name to load, or a URI.
+ * @error: (optional): return location for errors
+ *
+ * Loads the SVG specified by @file_name.  Note that this function, like
+ * rsvg_handle_new(), does not specify any loading flags for the resulting
+ * handle.  If you require the use of #RsvgHandleFlags, use
+ * rsvg_handle_new_from_gfile_sync().
+ *
+ * Returns: A #RsvgHandle or %NULL if an error occurs.
+ * Since: 2.14
+ */
 RSVG_API
 RsvgHandle *rsvg_handle_new_from_file (const gchar *filename, GError **error);
 
+/**
+ * rsvg_handle_set_stylesheet:
+ * @handle: A #RsvgHandle.
+ * @css: (array length=css_len): String with CSS data; must be valid UTF-8.
+ * @css_len: Length of the @css data in bytes.
+ * @error: (optional): return location for errors.
+ *
+ * Sets a CSS stylesheet to use for an SVG document.
+ *
+ * The @css_len argument is mandatory; this function will not compute the length
+ * of the @css string.  This is because a provided stylesheet, which the calling
+ * program could read from a file, can have nul characters in it.
+ *
+ * During the CSS cascade, the specified stylesheet will be used with a "User"
+ * <ulink
+ * url="https://drafts.csswg.org/css-cascade-3/#cascading-origins">origin</ulink>.
+ *
+ * Note that `@import` rules will not be resolved, except for `data:` URLs.
+ *
+ * Since: 2.48
+ */
 RSVG_API
 gboolean rsvg_handle_set_stylesheet (RsvgHandle   *handle,
                                      const guint8 *css,
@@ -350,6 +1109,14 @@ gboolean rsvg_handle_set_stylesheet (RsvgHandle   *handle,
                                      GError      **error);
 
 #ifndef __GTK_DOC_IGNORE__
+/**
+ * rsvg_handle_internal_set_testing:
+ * @handle: a #RsvgHandle
+ * @testing: Whether to enable testing mode
+ *
+ * Do not call this function.  This is intended for librsvg's internal
+ * test suite only.
+ **/
 RSVG_API
 void rsvg_handle_internal_set_testing (RsvgHandle *handle, gboolean testing);
 #endif /* __GTK_DOC_IGNORE__ */
@@ -358,11 +1125,35 @@ void rsvg_handle_internal_set_testing (RsvgHandle *handle, gboolean testing);
 
 #ifndef __GI_SCANNER__
 
+/**
+ * rsvg_init:
+ *
+ * This function does nothing.
+ *
+ * Since: 2.9
+ * Deprecated: 2.36: There is no need to initialize librsvg.
+ **/
 RSVG_DEPRECATED_FOR(g_type_init)
 void rsvg_init (void);
+
+/**
+ * rsvg_term:
+ *
+ * This function does nothing.
+ *
+ * Since: 2.9
+ * Deprecated: 2.36: There is no need to de-initialize librsvg.
+ **/
 RSVG_DEPRECATED
 void rsvg_term (void);
 
+/**
+ * rsvg_handle_free:
+ * @handle: An #RsvgHandle
+ *
+ * Frees @handle.
+ * Deprecated: Use g_object_unref() instead.
+ **/
 RSVG_DEPRECATED_FOR(g_object_unref)
 void rsvg_handle_free (RsvgHandle *handle);
 
@@ -380,6 +1171,63 @@ void rsvg_handle_free (RsvgHandle *handle);
  */
 typedef void (*RsvgSizeFunc) (gint * width, gint * height, gpointer user_data);
 
+/**
+ * rsvg_handle_set_size_callback:
+ * @handle: An #RsvgHandle
+ * @size_func: (nullable): A sizing function, or %NULL
+ * @user_data: User data to pass to @size_func, or %NULL
+ * @user_data_destroy: Function to be called to destroy the data passed in @user_data,
+ *   or %NULL.
+ *
+ * Sets the sizing function for the @handle, which can be used to override the
+ * size that librsvg computes for SVG images.  The @size_func is called from the
+ * following functions:
+ *
+ * <itemizedlist>
+ *   <listitem>rsvg_handle_get_dimensions()</listitem>
+ *   <listitem>rsvg_handle_get_dimensions_sub()</listitem>
+ *   <listitem>rsvg_handle_get_position_sub()</listitem>
+ *   <listitem>rsvg_handle_render_cairo()</listitem>
+ *   <listitem>rsvg_handle_render_cairo_sub()</listitem>
+ * </itemizedlist>
+ *
+ * Librsvg computes the size of the SVG being rendered, and passes it to the
+ * @size_func, which may then modify these values to set the final size of the
+ * generated image.
+ *
+ * Deprecated: 2.14.  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);
+ * }
+ * ]|
+ *
+ * This function was deprecated because when the @size_func is used, it makes it
+ * unclear when the librsvg functions which call the @size_func will use the
+ * size computed originally, or the callback-specified size, or whether it
+ * refers to the whole SVG or to just a sub-element of it.  It is easier, and
+ * unambiguous, to use code similar to the example above.
+ **/
 RSVG_DEPRECATED
 void rsvg_handle_set_size_callback (RsvgHandle    *handle,
                                     RsvgSizeFunc   size_func,
@@ -388,24 +1236,112 @@ void rsvg_handle_set_size_callback (RsvgHandle    *handle,
 
 /* GdkPixbuf convenience API */
 
+/**
+ * SECTION: rsvg-pixbuf
+ * @short_description: How to render SVGs into GdkPixbufs, for easy use in GTK+
+ *  applications
+ *
+ * GdkPixbuf is a library for image loading and manipulation. It is part of the
+ * cross-platform GTK+ widget toolkit.
+ */
+
+/**
+ * rsvg_pixbuf_from_file:
+ * @filename: A file name
+ * @error: return location for errors
+ * 
+ * Loads a new #GdkPixbuf from @filename and returns it.  The caller must
+ * assume the reference to the reurned pixbuf. If an error occurred, @error is
+ * set and %NULL is returned.
+ * 
+ * Return value: A newly allocated #GdkPixbuf, or %NULL
+ * Deprecated: Set up a cairo matrix and use rsvg_handle_new_from_file() + rsvg_handle_render_cairo() instead.
+ **/
 RSVG_DEPRECATED
-GdkPixbuf *rsvg_pixbuf_from_file            (const gchar *filename,
-                                             GError     **error);
+GdkPixbuf *rsvg_pixbuf_from_file (const gchar *filename,
+                                  GError     **error);
+
+/**
+ * rsvg_pixbuf_from_file_at_zoom:
+ * @filename: A file name
+ * @x_zoom: The horizontal zoom factor
+ * @y_zoom: The vertical zoom factor
+ * @error: return location for errors
+ * 
+ * Loads a new #GdkPixbuf from @filename and returns it.  This pixbuf is scaled
+ * from the size indicated by the file by a factor of @x_zoom and @y_zoom.  The
+ * caller must assume the reference to the returned pixbuf. If an error
+ * occurred, @error is set and %NULL is returned.
+ * 
+ * Return value: A newly allocated #GdkPixbuf, or %NULL
+ * Deprecated: Set up a cairo matrix and use rsvg_handle_new_from_file() + rsvg_handle_render_cairo() instead.
+ **/
 RSVG_DEPRECATED
-GdkPixbuf *rsvg_pixbuf_from_file_at_zoom    (const gchar *filename,
-                                             double       x_zoom,
-                                             double       y_zoom,
-                                             GError     **error);
+GdkPixbuf *rsvg_pixbuf_from_file_at_zoom (const gchar *filename,
+                                          double       x_zoom,
+                                          double       y_zoom,
+                                          GError     **error);
+
+/**
+ * rsvg_pixbuf_from_file_at_size:
+ * @filename: A file name
+ * @width: The new width, or -1
+ * @height: The new height, or -1
+ * @error: return location for errors
+ * 
+ * Loads a new #GdkPixbuf from @filename and returns it.  This pixbuf is scaled
+ * from the size indicated to the new size indicated by @width and @height.  If
+ * both of these are -1, then the default size of the image being loaded is
+ * used.  The caller must assume the reference to the returned pixbuf. If an
+ * error occurred, @error is set and %NULL is returned.
+ * 
+ * Return value: A newly allocated #GdkPixbuf, or %NULL
+ * Deprecated: Set up a cairo matrix and use rsvg_handle_new_from_file() + rsvg_handle_render_cairo() instead.
+ **/
 RSVG_DEPRECATED
-GdkPixbuf *rsvg_pixbuf_from_file_at_size    (const gchar *filename,
-                                             gint         width,
-                                             gint         height,
-                                             GError     **error);
+GdkPixbuf *rsvg_pixbuf_from_file_at_size (const gchar *filename,
+                                          gint         width,
+                                          gint         height,
+                                          GError     **error);
+
+/**
+ * rsvg_pixbuf_from_file_at_max_size:
+ * @filename: A file name
+ * @max_width: The requested max width
+ * @max_height: The requested max height
+ * @error: return location for errors
+ * 
+ * Loads a new #GdkPixbuf from @filename and returns it.  This pixbuf is uniformly
+ * scaled so that the it fits into a rectangle of size max_width * max_height. The
+ * caller must assume the reference to the returned pixbuf. If an error occurred,
+ * @error is set and %NULL is returned.
+ * 
+ * Return value: A newly allocated #GdkPixbuf, or %NULL
+ * Deprecated: Set up a cairo matrix and use rsvg_handle_new_from_file() + rsvg_handle_render_cairo() instead.
+ **/
 RSVG_DEPRECATED
-GdkPixbuf *rsvg_pixbuf_from_file_at_max_size    (const gchar *filename,
-                                                 gint         max_width,
-                                                 gint         max_height,
-                                                 GError     **error);
+GdkPixbuf *rsvg_pixbuf_from_file_at_max_size (const gchar *filename,
+                                              gint         max_width,
+                                              gint         max_height,
+                                              GError     **error);
+/**
+ * rsvg_pixbuf_from_file_at_zoom_with_max:
+ * @filename: A file name
+ * @x_zoom: The horizontal zoom factor
+ * @y_zoom: The vertical zoom factor
+ * @max_width: The requested max width
+ * @max_height: The requested max height
+ * @error: return location for errors
+ * 
+ * Loads a new #GdkPixbuf from @filename and returns it.  This pixbuf is scaled
+ * from the size indicated by the file by a factor of @x_zoom and @y_zoom. If the
+ * resulting pixbuf would be larger than max_width/max_heigh it is uniformly scaled
+ * down to fit in that rectangle. The caller must assume the reference to the
+ * returned pixbuf. If an error occurred, @error is set and %NULL is returned.
+ * 
+ * Return value: A newly allocated #GdkPixbuf, or %NULL
+ * Deprecated: Set up a cairo matrix and use rsvg_handle_new_from_file() + rsvg_handle_render_cairo() instead.
+ **/
 RSVG_DEPRECATED
 GdkPixbuf *rsvg_pixbuf_from_file_at_zoom_with_max (const gchar *filename,
                                                    double       x_zoom,
@@ -414,12 +1350,47 @@ GdkPixbuf *rsvg_pixbuf_from_file_at_zoom_with_max (const gchar *filename,
                                                    gint         max_height,
                                                    GError     **error);
 
+/**
+ * rsvg_handle_get_title:
+ * @handle: An #RsvgHandle
+ *
+ * Returns: (nullable): This function always returns NULL.
+ *
+ * Since: 2.4
+ *
+ * Deprecated: 2.36.  Librsvg does not read the metadata/desc/title elements;
+ * this function always returns #NULL.
+ */
 RSVG_DEPRECATED
-const char *rsvg_handle_get_title       (RsvgHandle *handle);
+const char *rsvg_handle_get_title (RsvgHandle *handle);
+
+/**
+ * rsvg_handle_get_desc:
+ * @handle: An #RsvgHandle
+ *
+ * Returns: (nullable): This function always returns NULL.
+ *
+ * Since: 2.4
+ *
+ * Deprecated: 2.36.  Librsvg does not read the metadata/desc/title elements;
+ * this function always returns #NULL.
+ */
 RSVG_DEPRECATED
-const char *rsvg_handle_get_desc        (RsvgHandle *handle);
+const char *rsvg_handle_get_desc (RsvgHandle *handle);
+
+/**
+ * rsvg_handle_get_metadata:
+ * @handle: An #RsvgHandle
+ *
+ * Returns: (nullable): This function always returns #NULL.
+ *
+ * Since: 2.9
+ *
+ * Deprecated: 2.36.  Librsvg does not read the metadata/desc/title elements;
+ * this function always returns #NULL.
+ */
 RSVG_DEPRECATED
-const char *rsvg_handle_get_metadata    (RsvgHandle *handle);
+const char *rsvg_handle_get_metadata (RsvgHandle *handle);
 
 #endif /* !__GI_SCANNER__ */
 
diff --git a/rsvg-c-srcs.mk b/rsvg-c-srcs.mk
index 2b283e55..ffc07b7c 100644
--- a/rsvg-c-srcs.mk
+++ b/rsvg-c-srcs.mk
@@ -1,19 +1,12 @@
-headers =			\

+librsvg_public_headers =	\

 	librsvg/rsvg.h		\

 	librsvg/rsvg-cairo.h	\

-	librsvg/rsvg-features.h

-

-extra_inc_headers =	\

-	librsvg/rsvg-version.h

+	librsvg/rsvg-features.h \

+	librsvg/rsvg-version.h	\

+	$(NULL)

 

-librsvg_c_srcs =	\

-	librsvg/rsvg-base.c		\

-	librsvg/rsvg-cairo.h		\

-	librsvg/rsvg-css.h 		\

-	librsvg/rsvg-features.h 	\

-	librsvg/rsvg-handle.c		\

-	librsvg/rsvg-pixbuf.c		\

-	librsvg/rsvg.h			\

+librsvg_private_headers = 	\

+	librsvg/rsvg-css.h	\

 	$(NULL)

 

 rsvg_convert_srcs = rsvg-convert.c