[librsvg: 1/23] rsvg.h - first pass at conversion to Markdown
- From: Marge Bot <marge-bot src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [librsvg: 1/23] rsvg.h - first pass at conversion to Markdown
- Date: Fri, 7 Jan 2022 02:11:38 +0000 (UTC)
commit eff053dfa02c22279bcedfcb33725cc7fafa0dbc
Author: Federico Mena Quintero <federico gnome org>
Date: Wed Jan 5 18:41:14 2022 -0600
rsvg.h - first pass at conversion to Markdown
Part-of: <https://gitlab.gnome.org/GNOME/librsvg/-/merge_requests/650>
include/librsvg/rsvg.h | 561 +++++++++++++++++++++++--------------------------
1 file changed, 267 insertions(+), 294 deletions(-)
---
diff --git a/include/librsvg/rsvg.h b/include/librsvg/rsvg.h
index d222b75eb..3c5c99a3e 100644
--- a/include/librsvg/rsvg.h
+++ b/include/librsvg/rsvg.h
@@ -79,111 +79,97 @@ GType rsvg_error_get_type (void);
#define RSVG_TYPE_ERROR (rsvg_error_get_type())
/**
- * SECTION: rsvg-handle
- * @short_description: Loads SVG data into memory.
+ * RsvgHandle:
+ *
+ * `RsvgHandle` loads an SVG document into memory.
*
- * This is the main entry point into the librsvg library. An RsvgHandle is an
+ * 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.
+ * `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.
+ * Librsvg supports reading [SVG 1.1](https://www.w3.org/TR/SVG11/) data, and is gradually
+ * adding support for features in [SVG 2](https://www.w3.org/TR/SVG2/). Librsvg also
+ * supports SVGZ files, which are just an SVG stream compressed with the GZIP algorithm.
+ *
+ * [static mode]: https://www.w3.org/TR/SVG2/conform.html#static-mode
+ * [secure static mode]: https://www.w3.org/TR/SVG2/conform.html#secure-static-mode
*
* # 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>
+ * entities. For example, say you have an SVG in `/foo/bar/foo.svg`
* 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>.
+ * `/foo/bar/foo.svg` so that it can generate the appropriate
+ * reference to `/foo/bar/resources/foo.png`.
*
* ## 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
+ * if the base file is `/foo/bar/baz.svg`, then librsvg will
* only try to load referenced files (from SVG's
- * <literal><image></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.
+ * `<image>` element, for example, or from content
+ * included through XML entities) if those files are in `/foo/bar/*` or in `/foo/bar/*/.../*`.
+ * 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>
+ * 1. All `data:` URLs may be loaded. These are sometimes used
+ * to include raster image data, encoded as base-64, directly in an SVG file.
+ *
+ * 2. 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).
+ *
+ * 3. 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
+ * "`file`" scheme, then all URL references inside the SVG must
+ * also have the "`file`" scheme, or be relative references which
+ * will be resolved against the base URL.
+ *
+ * 4. If referenced URLs have a "`resource`" 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 "`resource`", per the previous rule).
+ *
+ * 5. Otherwise, non-`file` schemes are not allowed. For
+ * example, librsvg will not load `http` resources, to keep
+ * malicious SVG data from "phoning home".
+ *
+ * 6. 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.
*
* # Loading an SVG with GIO
*
* This is the easiest and most resource-efficient way of loading SVG data into
- * an #RsvgHandle.
+ * 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.
+ * 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
+ * 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
+ * Both of those methods allow specifying a `GCancellable`, so the loading
* process can be cancelled from another thread.
*
* ## Loading an SVG from memory
@@ -198,10 +184,10 @@ GType rsvg_error_get_type (void);
*
* # Loading an SVG without GIO
*
- * You can load an RsvgHandle from a simple filename or URI with
+ * 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.
+ * 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
@@ -212,8 +198,8 @@ GType rsvg_error_get_type (void);
*
* # 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
+ * SVG images can contain dimensions like "`5cm`" or
+ * "`2pt`" 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
@@ -227,25 +213,20 @@ GType rsvg_error_get_type (void);
*
* # API ordering
*
- * Due to the way the librsvg API evolved over time, an #RsvgHandle object is available
+ * 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()
+ * 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_render_document() on it
* just at that point.
*
- * The documentation for the available methods in #RsvgHandle may mention that a particular
+ * 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>
+ * * The handle was loaded with rsvg_handle_write() and rsvg_handle_close(), and
+ * those functions returned no errors.
+ *
+ * * The handle was loaded with rsvg_handle_read_stream_sync() and that function
+ * returned no errors.
*
* 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
@@ -263,7 +244,7 @@ GType rsvg_error_get_type (void);
/**
* RsvgHandle:flags:
*
- * Flags from #RsvgHandleFlags.
+ * Flags from `RsvgHandleFlags`.
*
* Since: 2.36
*/
@@ -284,6 +265,7 @@ GType rsvg_error_get_type (void);
* RsvgHandle::base-uri:
*
* Base URI, to be used to resolve relative references for resources. See the section
+ * "Security and locations of referenced files" for details.
*/
/**
@@ -295,8 +277,8 @@ GType rsvg_error_get_type (void);
* 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.
+ * be recomputed, so reading both the `width` and
+ * `height` properties will cause two such computations.
* Please use rsvg_handle_get_intrinsic_dimensions() instead.
*/
@@ -309,8 +291,8 @@ GType rsvg_error_get_type (void);
* 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.
+ * be recomputed, so reading both the `width` and
+ * `height` properties will cause two such computations.
* Please use rsvg_handle_get_intrinsic_dimensions() instead.
*/
@@ -321,8 +303,8 @@ GType rsvg_error_get_type (void);
* 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
+ * SVG to be recomputed, so reading both the `em` and
+ * `ex` properties will cause two such computations. Please
* use rsvg_handle_get_intrinsic_dimensions() instead.
*/
@@ -333,8 +315,8 @@ GType rsvg_error_get_type (void);
* 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
+ * SVG to be recomputed, so reading both the `em` and
+ * `ex` properties will cause two such computations. Please
* use rsvg_handle_get_intrinsic_dimensions() instead.
*/
@@ -343,7 +325,7 @@ GType rsvg_error_get_type (void);
*
* SVG's title.
*
- * Deprecated: 2.36. Reading this property always returns #NULL.
+ * Deprecated: 2.36. Reading this property always returns `NULL`.
*/
/**
@@ -351,7 +333,7 @@ GType rsvg_error_get_type (void);
*
* SVG's description.
*
- * Deprecated: 2.36. Reading this property always returns #NULL.
+ * Deprecated: 2.36. Reading this property always returns `NULL`.
*/
/**
@@ -359,7 +341,7 @@ GType rsvg_error_get_type (void);
*
* SVG's metadata
*
- * Deprecated: 2.36. Reading this property always returns #NULL.
+ * Deprecated: 2.36. Reading this property always returns `NULL`.
*/
/***** End documentation for RsvgHandle properties *****/
@@ -384,7 +366,7 @@ typedef struct _RsvgRectangle RsvgRectangle;
* RsvgHandleClass:
* @parent: parent class
*
- * Class structure for #RsvgHandle.
+ * Class structure for `RsvgHandle`.
*/
struct _RsvgHandleClass {
GObjectClass parent;
@@ -410,8 +392,8 @@ struct _RsvgHandle {
* RsvgDimensionData:
* @width: SVG's width, in pixels
* @height: SVG's height, in pixels
- * @em: SVG's original width, unmodified by #RsvgSizeFunc
- * @ex: SVG's original height, unmodified by #RsvgSizeFunc
+ * @em: SVG's original width, unmodified by `RsvgSizeFunc`
+ * @ex: SVG's original height, unmodified by `RsvgSizeFunc`
*
* Dimensions of an SVG image from rsvg_handle_get_dimensions(), or an
* individual element from rsvg_handle_get_dimensions_sub(). Please see
@@ -473,13 +455,13 @@ 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
+ * 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
+ * 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.
*/
@@ -491,13 +473,13 @@ void rsvg_set_default_dpi (double dpi);
* @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
+ * 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
+ * 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.
*/
@@ -506,7 +488,7 @@ void rsvg_set_default_dpi_x_y (double dpi_x, double dpi_y);
/**
* rsvg_handle_set_dpi:
- * @handle: An #RsvgHandle
+ * @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
@@ -523,7 +505,7 @@ void rsvg_handle_set_dpi (RsvgHandle *handle, double dpi);
/**
* rsvg_handle_set_dpi_x_y:
- * @handle: An #RsvgHandle
+ * @handle: An `RsvgHandle`
* @dpi_x: Dots Per Inch (i.e. Pixels Per Inch)
* @dpi_y: Dots Per Inch (i.e. Pixels Per Inch)
*
@@ -545,7 +527,7 @@ void rsvg_handle_set_dpi_x_y (RsvgHandle *handle, double dpi_x, double dpi_y);
* 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
+ * 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
@@ -554,26 +536,26 @@ void rsvg_handle_set_dpi_x_y (RsvgHandle *handle, double dpi_x, double dpi_y);
* 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
+ * 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
+ * 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.
+ * Returns: A new `RsvgHandle` with no flags set.
**/
RSVG_API
RsvgHandle *rsvg_handle_new (void);
/**
* rsvg_handle_write:
- * @handle: an #RsvgHandle
+ * @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
+ * @error: (optional): a location to store a `GError`, or `NULL`
*
* Loads the next @count bytes of the image. You can call this function multiple
* times until the whole document is consumed; then you must call rsvg_handle_close()
@@ -582,17 +564,17 @@ RsvgHandle *rsvg_handle_new (void);
* 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><image></literal> which reference external resources will be
+ * `<image>` which reference external resources will be
* resolved relative to the location you specify with those functions.
*
- * Returns: %TRUE on success, or %FALSE on error.
+ * 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.
+ * 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,
@@ -602,8 +584,8 @@ gboolean rsvg_handle_write (RsvgHandle *handle,
/**
* rsvg_handle_close:
- * @handle: a #RsvgHandle
- * @error: (optional): a location to store a #GError, or %NULL
+ * @handle: a `RsvgHandle`
+ * @error: (optional): a location to store a `GError`, or `NULL`
*
* This is used after calling rsvg_handle_write() to indicate that there is no more data
* to consume, and to start the actual parsing of the SVG document. The only reason to
@@ -611,11 +593,11 @@ gboolean rsvg_handle_write (RsvgHandle *handle,
* if you use the other methods like rsvg_handle_new_from_file() or
* rsvg_handle_read_stream_sync(), then you do not need to call this function.
*
- * This will return %TRUE if the loader closed successfully and the
+ * 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.
+ * 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
@@ -627,19 +609,19 @@ gboolean rsvg_handle_close (RsvgHandle *handle, GError **error);
/**
* rsvg_handle_get_pixbuf:
- * @handle: An #RsvgHandle
+ * @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.
*
* API ordering: This function must be called on a fully-loaded @handle. See
- * the section <ulink url="RsvgHandle.html#API-ordering">API ordering</ulink> for details.
+ * the section "API ordering" for details.
*
- * This function depends on the #RsvgHandle's dots-per-inch value (DPI) to compute the
+ * This function depends on the `RsvgHandle`'s dots-per-inch value (DPI) to compute the
* "natural size" of the document in pixels, so you should call rsvg_handle_set_dpi()
* beforehand.
*
- * Returns: (transfer full) (nullable): a pixbuf, or %NULL if an error occurs
+ * Returns: (transfer full) (nullable): a pixbuf, or `NULL` if an error occurs
* during rendering.
**/
RSVG_API
@@ -649,15 +631,15 @@ 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.
+ * 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
+ * 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
+ * sub-sub-elements recursively). If @id is `NULL`, this function renders the
* whole SVG.
*
- * This function depends on the #RsvgHandle's dots-per-inch value (DPI) to compute the
+ * This function depends on the `RsvgHandle`'s dots-per-inch value (DPI) to compute the
* "natural size" of the document in pixels, so you should call rsvg_handle_set_dpi()
* beforehand.
*
@@ -665,13 +647,13 @@ GdkPixbuf *rsvg_handle_get_pixbuf (RsvgHandle *handle);
* sub-element of the SVG, consider using 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.
+ * `#foo` (hash `foo`) to get the geometry of the element that
+ * has an `id="foo"` attribute.
*
* API ordering: This function must be called on a fully-loaded @handle. See
- * the section <ulink url="RsvgHandle.html#API-ordering">API ordering</ulink> for details.
+ * the section "API ordering" for details.
*
- * Returns: (transfer full) (nullable): a pixbuf, or %NULL if an error occurs
+ * Returns: (transfer full) (nullable): a pixbuf, or `NULL` if an error occurs
* during rendering.
*
* Since: 2.14
@@ -693,7 +675,7 @@ const char *rsvg_handle_get_base_uri (RsvgHandle *handle);
/**
* rsvg_handle_set_base_uri:
- * @handle: A #RsvgHandle
+ * @handle: A `RsvgHandle`
* @base_uri: The base uri
*
* Set the base URI for this SVG.
@@ -708,13 +690,13 @@ void rsvg_handle_set_base_uri (RsvgHandle *handle, const char *base_uri);
/**
* rsvg_handle_get_dimensions:
- * @handle: A #RsvgHandle
+ * @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
+ * This function depends on the `RsvgHandle`'s DPI to compute dimensions in
* pixels, so you should call rsvg_handle_set_dpi() beforehand.
*
* Deprecated: 2.52. Use rsvg_handle_get_intrinsic_size_in_pixels() instead. This
@@ -728,21 +710,21 @@ void rsvg_handle_get_dimensions (RsvgHandle *handle, RsvgDimensionData *dimensio
/**
* rsvg_handle_get_dimensions_sub:
- * @handle: A #RsvgHandle
+ * @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.
+ * 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
+ * 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.
+ * `#foo` (hash `foo`) to get the geometry of the element that
+ * has an `id="foo"` attribute.
*
* Deprecated: 2.46. Use rsvg_handle_get_geometry_for_layer() instead.
*
@@ -755,21 +737,21 @@ gboolean rsvg_handle_get_dimensions_sub (RsvgHandle *handle,
/**
* rsvg_handle_get_position_sub:
- * @handle: A #RsvgHandle
+ * @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
+ * 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
+ * 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.
+ * `#foo` (hash `foo`) to get the geometry of the element that
+ * has an `id="foo"` attribute.
*
* Deprecated: 2.46. Use rsvg_handle_get_geometry_for_layer() instead. This function is
* deprecated since it is not able to return exact floating-point positions, only integer
@@ -784,18 +766,18 @@ gboolean rsvg_handle_get_position_sub (RsvgHandle *handle,
/**
* rsvg_handle_has_sub:
- * @handle: a #RsvgHandle
+ * @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
+ * 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.
+ * `#foo` (hash `foo`) to get the geometry of the element that
+ * has an `id="foo"` attribute.
*
- * Returns: %TRUE if @id exists in the SVG document, %FALSE otherwise.
+ * Returns: `TRUE` if @id exists in the SVG document, `FALSE` otherwise.
*
* Since: 2.22
*/
@@ -814,9 +796,8 @@ gboolean rsvg_handle_has_sub (RsvgHandle *handle, const char *id);
* @RSVG_UNIT_PT: points, or 1/72 inch
* @RSVG_UNIT_PC: picas, or 1/6 inch (12 points)
*
- * Units for the #RsvgLength struct. These have the same meaning as <ulink
- * url="https://www.w3.org/TR/CSS21/syndata.html#length-units";>CSS length
- * units</ulink>.
+ * Units for the `RsvgLength` struct. These have the same meaning as [CSS length
+ * units](https://www.w3.org/TR/CSS21/syndata.html#length-units).
*/
typedef enum {
RSVG_UNIT_PERCENT,
@@ -835,19 +816,17 @@ typedef enum {
* @length: numeric part of the length
* @unit: unit part of the length
*
- * #RsvgLength values are used in rsvg_handle_get_intrinsic_dimensions(), for
- * example, to return the CSS length values of the <literal>width</literal> and
- * <literal>height</literal> attributes of an <literal><svg></literal>
- * element.
+ * `RsvgLength` values are used in rsvg_handle_get_intrinsic_dimensions(), for
+ * example, to return the CSS length values of the `width` and
+ * `height` attributes of an `<svg>` element.
*
- * This is equivalent to <ulink
- * url="https://www.w3.org/TR/CSS21/syndata.html#length-units";>CSS lengths</ulink>.
+ * This is equivalent to [CSS lengths](https://www.w3.org/TR/CSS21/syndata.html#length-units).
*
* It is up to the calling application to convert lengths in non-pixel units
- * (i.e. those where the @unit field is not #RSVG_UNIT_PX) into something
+ * (i.e. those where the @unit field is not `RSVG_UNIT_PX`) into something
* meaningful to the application. For example, if your application knows the
* dots-per-inch (DPI) it is using, it can convert lengths with @unit in
- * #RSVG_UNIT_IN or other physical units.
+ * `RSVG_UNIT_IN` or other physical units.
*/
typedef struct {
double length;
@@ -856,43 +835,42 @@ typedef struct {
/**
* 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
+ * @handle: An `RsvgHandle`
+ * @out_has_width: (out)(optional): Will be set to `TRUE` if the toplevel SVG has a `width` attribute
+ * @out_width: (out)(optional): Will be set to the value of the `width` attribute in the toplevel SVG
+ * @out_has_height: (out)(optional): Will be set to `TRUE` if the toplevel SVG has a `height` attribute
+ * @out_height: (out)(optional): Will be set to the value of the `height` attribute in the toplevel SVG
+ * @out_has_viewbox: (out)(optional): Will be set to `TRUE` if the toplevel SVG has a `viewBox` attribute
+ * @out_viewbox: (out)(optional): Will be set to the value of the `viewBox` attribute in the toplevel SVG
*
- * Queries the <literal>width</literal>, <literal>height</literal>, and
- * <literal>viewBox</literal> attributes in an SVG document.
+ * Queries the `width`, `height`, and `viewBox` 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>:
+ * As an example, the following SVG element has a `width` of 100 pixels and a `height` of 400 pixels, but no
`viewBox`:
*
- * |[
+ * ```
* <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>:
+ * Conversely, the following element has a `viewBox`, but no `width` or `height`:
*
- * |[
+ * ```
* <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
+ * 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.
+ * will return width and height values whose `units` fields are `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="RsvgHandle.html#API-ordering">API ordering</ulink> for details.
+ * the section "API ordering" for details.
*
* Panics: this function will panic if the @handle is not fully-loaded.
*
@@ -909,62 +887,62 @@ void rsvg_handle_get_intrinsic_dimensions (RsvgHandle *handle,
/**
* rsvg_handle_get_intrinsic_size_in_pixels:
- * @handle: An #RsvgHandle
+ * @handle: An `RsvgHandle`
* @out_width: (out)(optional): Will be set to the computed width; you should round this up to get integer
pixels.
* @out_height: (out)(optional): Will be set to the computed height; you should round this up to get integer
pixels.
*
* Converts an SVG document's intrinsic dimensions to pixels, and returns the result.
*
* This function is able to extract the size in pixels from an SVG document if the
- * document has both <literal>width</literal> and <literal>height</literal> attributes
+ * document has both `width` and `height` attributes
* with physical units (px, in, cm, mm, pt, pc) or font-based units (em, ex). For
* physical units, the dimensions are normalized to pixels using the dots-per-inch (DPI)
* value set previously with rsvg_handle_set_dpi(). For font-based units, this function
* uses the computed value of the `font-size` property for the toplevel
- * <literal><svg></literal> element. In those cases, this function returns %TRUE.
+ * `<svg>` element. In those cases, this function returns `TRUE`.
*
* This function is not able to extract the size in pixels directly from the intrinsic
- * dimensions of the SVG document if the <literal>width</literal> or
- * <literal>height</literal> are in percentage units (or if they do not exist, in which
+ * dimensions of the SVG document if the `width` or
+ * `height` are in percentage units (or if they do not exist, in which
* case the SVG spec mandates that they default to 100%), as these require a
* <firstterm>viewport</firstterm> to be resolved to a final size. In this case, the
- * function returns %FALSE.
+ * function returns `FALSE`.
*
* For example, the following document fragment has intrinsic dimensions that will resolve
* to 20x30 pixels.
*
- * |[
+ * ```
* <svg xmlns="http://www.w3.org/2000/svg"; width="20" height="30"/>
- * ]|
+ * ```
*
* Similarly, if the DPI is set to 96, this document will resolve to 192x288 pixels (i.e. 96*2 x 96*3).
*
- * |[
+ * ```
* <svg xmlns="http://www.w3.org/2000/svg"; width="2in" height="3in"/>
- * ]|
+ * ```
*
* The dimensions of the following documents cannot be resolved to pixels directly, and
- * this function would return %FALSE for them:
+ * this function would return `FALSE` for them:
*
- * |[
+ * ```
* <!-- Needs a viewport against which to compute the percentages. -->
* <svg xmlns="http://www.w3.org/2000/svg"; width="100%" height="100%"/>
*
* <!-- Does not have intrinsic width/height, just a 1:2 aspect ratio which
* needs to be fitted within a viewport. -->
* <svg xmlns="http://www.w3.org/2000/svg"; viewBox="0 0 100 200"/>
- * ]|
+ * ```
*
* Instead of querying an SVG document's size, applications are encouraged to render SVG
* documents to a size chosen by the application, by passing a suitably-sized viewport to
* rsvg_handle_render_document().
*
- * Returns: %TRUE if the dimensions could be converted directly to pixels; in this case
+ * Returns: `TRUE` if the dimensions could be converted directly to pixels; in this case
* @out_width and @out_height will be set accordingly. Note that the dimensions are
* floating-point numbers, so your application can know the exact size of an SVG document.
* To get integer dimensions, you should use `ceil()` to round up to the nearest integer
* (just using `round()`, may may chop off pixels with fractional coverage). If the
- * dimensions cannot be converted to pixels, returns %FALSE and puts 0.0 in both
+ * dimensions cannot be converted to pixels, returns `FALSE` and puts 0.0 in both
* @out_width and @out_height.
*
* Since: 2.52
@@ -979,23 +957,21 @@ gboolean rsvg_handle_get_intrinsic_size_in_pixels (RsvgHandle *handle,
/**
* RsvgHandleFlags:
* @RSVG_HANDLE_FLAGS_NONE: No flags are set.
- * @RSVG_HANDLE_FLAG_UNLIMITED: Disable safety limits in the XML parser.
- * Libxml2 has <ulink
- * url="https://gitlab.gnome.org/GNOME/libxml2/blob/master/include/libxml/parserInternals.h";>several
- * limits</ulink> designed to keep malicious XML content from consuming too
- * much memory while parsing. For security reasons, this should only be used
- * for trusted input!
- * Since: 2.40.3
- * @RSVG_HANDLE_FLAG_KEEP_IMAGE_DATA: Use this if the Cairo surface to which you
- * are rendering is a PDF, PostScript, SVG, or Win32 Printing surface. This
- * will make librsvg and Cairo use the original, compressed data for images in
- * the final output, instead of passing uncompressed images. This will make a
- * Keeps the image data when loading images, for use by cairo when painting to
- * e.g. a PDF surface. For example, this will make the a resulting PDF file
- * smaller and faster. Please see <ulink
- * url="https://www.cairographics.org/manual/cairo-cairo-surface-t.html#cairo-surface-set-mime-data";>the
- * Cairo documentation</ulink> for details.
- * Since: 2.40.3
+ *
+ * @RSVG_HANDLE_FLAG_UNLIMITED: Disable safety limits in the XML parser. Libxml2 has
+ * [several limits](https://gitlab.gnome.org/GNOME/libxml2/blob/master/include/libxml/parserInternals.h)
+ * designed to keep malicious XML content from consuming too much memory while parsing.
+ * For security reasons, this should only be used for trusted input! Since: 2.40.3
+ *
+ * @RSVG_HANDLE_FLAG_KEEP_IMAGE_DATA: Use this if the Cairo surface to which you are
+ * rendering is a PDF, PostScript, SVG, or Win32 Printing surface. This will make librsvg
+ * and Cairo use the original, compressed data for images in the final output, instead of
+ * passing uncompressed images. For example, this will make the a resulting PDF file
+ * smaller and faster. Please see [the Cairo
+ *
documentation](https://www.cairographics.org/manual/cairo-cairo-surface-t.html#cairo-surface-set-mime-data)
+ * for details.
+ *
+ * Since: 2.40.3
*/
typedef enum /*< flags >*/
{
@@ -1010,13 +986,13 @@ GType rsvg_handle_flags_get_type (void);
/**
* rsvg_handle_new_with_flags:
- * @flags: flags from #RsvgHandleFlags
+ * @flags: flags from `RsvgHandleFlags`
*
- * Creates a new #RsvgHandle with flags @flags. After calling this function,
+ * 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
+ * Returns: (transfer full): a new `RsvgHandle`
*
* Since: 2.36
**/
@@ -1025,8 +1001,8 @@ RsvgHandle *rsvg_handle_new_with_flags (RsvgHandleFlags flags);
/**
* rsvg_handle_set_base_gfile:
- * @handle: a #RsvgHandle
- * @base_file: a #GFile
+ * @handle: a `RsvgHandle`
+ * @base_file: a `GFile`
*
* Set the base URI for @handle from @file.
*
@@ -1041,25 +1017,25 @@ void rsvg_handle_set_base_gfile (RsvgHandle *handle,
/**
* 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
+ * @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><image></literal> which reference external resources will be
+ * `<image>` 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
+ * 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
+ * operation was cancelled, the error `G_IO_ERROR_CANCELLED` will be
* returned.
*
- * Returns: %TRUE if reading @stream succeeded, or %FALSE otherwise
+ * Returns: `TRUE` if reading @stream succeeded, or `FALSE` otherwise
* with @error filled in
*
* Since: 2.32
@@ -1072,23 +1048,23 @@ gboolean rsvg_handle_read_stream_sync (RsvgHandle *handle,
/**
* 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
+ * @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.
+ * Creates a new `RsvgHandle` for @file.
*
* This function sets the "base file" of the handle to be @file itself, so SVG
- * elements like <literal><image></literal> which reference external
+ * elements like `<image>` 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
+ * 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
+ * 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
+ * Returns: a new `RsvgHandle` on success, or `NULL` with @error filled in
*
* Since: 2.32
*/
@@ -1100,24 +1076,24 @@ RsvgHandle *rsvg_handle_new_from_gfile_sync (GFile *file,
/**
* 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
+ * @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.
+ * 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><image></literal> which reference
+ * provided. SVG elements like `<image>` 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
+ * 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
+ * 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
+ * Returns: a new `RsvgHandle` on success, or `NULL` with @error filled in
*
* Since: 2.32
*/
@@ -1135,11 +1111,11 @@ RsvgHandle *rsvg_handle_new_from_stream_sync (GInputStream *input_stream,
* @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
+ * `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.
+ * a `GMemoryInputStream` from your data.
*
- * Returns: A #RsvgHandle or %NULL if an error occurs.
+ * Returns: A `RsvgHandle` or `NULL` if an error occurs.
* Since: 2.14
*/
RSVG_API
@@ -1152,10 +1128,10 @@ RsvgHandle *rsvg_handle_new_from_data (const guint8 *data, gsize data_len, GErro
*
* 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
+ * handle. If you require the use of `RsvgHandleFlags`, use
* rsvg_handle_new_from_gfile_sync().
*
- * Returns: A #RsvgHandle or %NULL if an error occurs.
+ * Returns: A `RsvgHandle` or `NULL` if an error occurs.
* Since: 2.14
*/
RSVG_API
@@ -1163,7 +1139,7 @@ RsvgHandle *rsvg_handle_new_from_file (const gchar *filename, GError **error);
/**
* rsvg_handle_set_stylesheet:
- * @handle: A #RsvgHandle.
+ * @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.
@@ -1175,8 +1151,7 @@ RsvgHandle *rsvg_handle_new_from_file (const gchar *filename, GError **error);
* 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>.
+ * [origin](https://drafts.csswg.org/css-cascade-3/#cascading-origins).
*
* Note that `@import` rules will not be resolved, except for `data:` URLs.
*
@@ -1191,7 +1166,7 @@ gboolean rsvg_handle_set_stylesheet (RsvgHandle *handle,
#ifndef __GTK_DOC_IGNORE__
/**
* rsvg_handle_internal_set_testing:
- * @handle: a #RsvgHandle
+ * @handle: a `RsvgHandle`
* @testing: Whether to enable testing mode
*
* Do not call this function. This is intended for librsvg's internal
@@ -1229,7 +1204,7 @@ void rsvg_term (void);
/**
* rsvg_handle_free:
- * @handle: An #RsvgHandle
+ * @handle: An `RsvgHandle`
*
* Frees @handle.
* Deprecated: Use g_object_unref() instead.
@@ -1255,23 +1230,21 @@ 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
+ * @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.
+ * 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>
+ * * rsvg_handle_get_dimensions()
+ * * rsvg_handle_get_dimensions_sub()
+ * * rsvg_handle_get_position_sub()
+ * * rsvg_handle_render_cairo()
+ * * rsvg_handle_render_cairo_sub()
*
* 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
@@ -1293,11 +1266,11 @@ void rsvg_handle_set_size_callback (RsvgHandle *handle,
/* GdkPixbuf convenience API */
/**
- * SECTION: rsvg-pixbuf
+ * rsvg-pixbuf:
*
* Years ago, GNOME and GTK used the gdk-pixbuf library as a general mechanism to load
* raster images into memory (PNG, JPEG, etc.) and pass them around. The general idiom
- * was, "load this image file and give me a #GdkPixbuf object", which is basically a pixel
+ * was, "load this image file and give me a `GdkPixbuf` object", which is basically a pixel
* buffer. Librsvg supports this kind of interface to load and render SVG documents, but
* it is deprecated in favor of rendering to Cairo contexts.
*/
@@ -1307,11 +1280,11 @@ void rsvg_handle_set_size_callback (RsvgHandle *handle,
* @filename: A file name
* @error: return location for errors
*
- * Loads a new #GdkPixbuf from @filename and returns it. The caller must
+ * 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.
+ * set and `NULL` is returned.
*
- * Return value: A newly allocated #GdkPixbuf, or %NULL
+ * Return value: A newly allocated `GdkPixbuf`, or %NULL
* Deprecated: Use rsvg_handle_new_from_file() and rsvg_handle_render_document() instead.
**/
RSVG_DEPRECATED
@@ -1325,12 +1298,12 @@ GdkPixbuf *rsvg_pixbuf_from_file (const gchar *filename,
* @y_zoom: The vertical zoom factor
* @error: return location for errors
*
- * Loads a new #GdkPixbuf from @filename and returns it. This pixbuf is scaled
+ * 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.
+ * occurred, @error is set and `NULL` is returned.
*
- * Return value: A newly allocated #GdkPixbuf, or %NULL
+ * Return value: A newly allocated `GdkPixbuf`, or %NULL
* Deprecated: Use rsvg_handle_new_from_file() and rsvg_handle_render_document() instead.
**/
RSVG_DEPRECATED
@@ -1346,13 +1319,13 @@ GdkPixbuf *rsvg_pixbuf_from_file_at_zoom (const gchar *filename,
* @height: The new height, or -1
* @error: return location for errors
*
- * Loads a new #GdkPixbuf from @filename and returns it. This pixbuf is scaled
+ * 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.
+ * error occurred, @error is set and `NULL` is returned.
*
- * Return value: A newly allocated #GdkPixbuf, or %NULL
+ * Return value: A newly allocated `GdkPixbuf`, or %NULL
* Deprecated: Use rsvg_handle_new_from_file() and rsvg_handle_render_document() instead.
**/
RSVG_DEPRECATED
@@ -1368,12 +1341,12 @@ GdkPixbuf *rsvg_pixbuf_from_file_at_size (const gchar *filename,
* @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
+ * 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.
+ * @error is set and `NULL` is returned.
*
- * Return value: A newly allocated #GdkPixbuf, or %NULL
+ * Return value: A newly allocated `GdkPixbuf`, or `NULL`
* Deprecated: Use rsvg_handle_new_from_file() and rsvg_handle_render_document() instead.
**/
RSVG_DEPRECATED
@@ -1390,13 +1363,13 @@ GdkPixbuf *rsvg_pixbuf_from_file_at_max_size (const gchar *filename,
* @max_height: The requested max height
* @error: return location for errors
*
- * Loads a new #GdkPixbuf from @filename and returns it. This pixbuf is scaled
+ * 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.
+ * returned pixbuf. If an error occurred, @error is set and `NULL` is returned.
*
- * Return value: A newly allocated #GdkPixbuf, or %NULL
+ * Return value: A newly allocated `GdkPixbuf`, or `NULL`
* Deprecated: Use rsvg_handle_new_from_file() and rsvg_handle_render_document() instead.
**/
RSVG_DEPRECATED
@@ -1409,28 +1382,28 @@ GdkPixbuf *rsvg_pixbuf_from_file_at_zoom_with_max (const gchar *filename,
/**
* rsvg_handle_get_title:
- * @handle: An #RsvgHandle
+ * @handle: An `RsvgHandle`
*
- * Returns: (nullable): This function always returns NULL.
+ * 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.
+ * this function always returns `NULL`.
*/
RSVG_DEPRECATED
const char *rsvg_handle_get_title (RsvgHandle *handle);
/**
* rsvg_handle_get_desc:
- * @handle: An #RsvgHandle
+ * @handle: An `RsvgHandle`
*
- * Returns: (nullable): This function always returns NULL.
+ * 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.
+ * this function always returns `NULL`.
*/
RSVG_DEPRECATED
const char *rsvg_handle_get_desc (RsvgHandle *handle);
@@ -1439,12 +1412,12 @@ const char *rsvg_handle_get_desc (RsvgHandle *handle);
* rsvg_handle_get_metadata:
* @handle: An #RsvgHandle
*
- * Returns: (nullable): This function always returns #NULL.
+ * 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.
+ * this function always returns `NULL`.
*/
RSVG_DEPRECATED
const char *rsvg_handle_get_metadata (RsvgHandle *handle);
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
