[librsvg: 3/23] rsvg-cairo.h: first pass at conversion to Markdown

From: Marge Bot <marge-bot src gnome org>
To: commits-list gnome org
Cc:
Subject: [librsvg: 3/23] rsvg-cairo.h: first pass at conversion to Markdown
Date: Fri, 7 Jan 2022 02:11:38 +0000 (UTC)

commit 3da89b75825f698a0f2ffa450f2863d12f0b6619
Author: Federico Mena Quintero <federico gnome org>
Date:   Wed Jan 5 19:00:26 2022 -0600

    rsvg-cairo.h: first pass at conversion to Markdown
    
    Part-of: <https://gitlab.gnome.org/GNOME/librsvg/-/merge_requests/650>

 include/librsvg/rsvg-cairo.h | 208 ++++++++++++++++++++-----------------------
 1 file changed, 97 insertions(+), 111 deletions(-)
---
diff --git a/include/librsvg/rsvg-cairo.h b/include/librsvg/rsvg-cairo.h
index 6716a9a6a..7153e5e7a 100644
--- a/include/librsvg/rsvg-cairo.h
+++ b/include/librsvg/rsvg-cairo.h
@@ -35,7 +35,7 @@ G_BEGIN_DECLS
 
 /**
  * rsvg_handle_render_cairo:
- * @handle: A #RsvgHandle
+ * @handle: A `RsvgHandle`
  * @cr: A Cairo context
  *
  * Draws a loaded SVG handle to a Cairo context.  Please try to use
@@ -44,48 +44,41 @@ G_BEGIN_DECLS
  *
  * Historically this function has picked a size by itself, based on the following rules:
  *
- * <itemizedlist>
- *   <listitem>
- *     If the SVG document has both <literal>width</literal> and <literal>height</literal>
- *     attributes with physical units (px, in, cm, mm, pt, pc) or font-based units (em,
- *     ex), the function computes the size directly based on the dots-per-inch (DPI) you
- *     have configured with rsvg_handle_set_dpi().  This is the same approach as
- *     rsvg_handle_get_intrinsic_size_in_pixels().
- *   </listitem>
- *   <listitem>
- *     Otherwise, if there is a <literal>viewBox</literal> attribute and both
- *     <literal>width</literal> and <literal>height</literal> are set to
- *     <literal>100%</literal> (or if they don't exist at all and thus default to 100%),
- *     the function uses the width and height of the viewBox as a pixel size.  This
- *     produces a rendered document with the correct aspect ratio.
- *   </listitem>
- *   <listitem>
- *      Otherwise, this function computes the extents of every graphical object in the SVG
- *      document to find the total extents.  This is moderately expensive, but no more expensive
- *      than rendering the whole document, for example.
- *   </listitem>
- *   <listitem>
- *     This function cannot deal with percentage-based units for <literal>width</literal>
- *     and <literal>height</literal> because there is no viewport against which they could
- *     be resolved; that is why it will compute the extents of objects in that case.  This
- *     is why we recommend that you use rsvg_handle_render_document() instead, which takes
- *     in a viewport and follows the sizing policy from the web platform.
- *   </listitem>
- * </itemizedlist>
+ * * If the SVG document has both `width` and `height`
+ *   attributes with physical units (px, in, cm, mm, pt, pc) or font-based units (em,
+ *   ex), the function computes the size directly based on the dots-per-inch (DPI) you
+ *   have configured with rsvg_handle_set_dpi().  This is the same approach as
+ *   rsvg_handle_get_intrinsic_size_in_pixels().
+ *
+ * * Otherwise, if there is a `viewBox` attribute and both
+ *   `width` and `height` are set to
+ *   `100%` (or if they don't exist at all and thus default to 100%),
+ *   the function uses the width and height of the `viewBox` as a pixel size.  This
+ *   produces a rendered document with the correct aspect ratio.
+ *
+ * * Otherwise, this function computes the extents of every graphical object in the SVG
+ *   document to find the total extents.  This is moderately expensive, but no more expensive
+ *   than rendering the whole document, for example.
+ *
+ * * This function cannot deal with percentage-based units for `width`
+ *   and `height` because there is no viewport against which they could
+ *   be resolved; that is why it will compute the extents of objects in that case.  This
+ *   is why we recommend that you use rsvg_handle_render_document() instead, which takes
+ *   in a viewport and follows the sizing policy from the web platform.
  *
  * 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
+ * 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
+ * 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.
+ * Returns: `TRUE` if drawing succeeded; `FALSE` otherwise.
  * Since: 2.14
  *
  * Deprecated: 2.52.  Please use rsvg_handle_render_document() instead; that function lets
@@ -96,11 +89,11 @@ gboolean rsvg_handle_render_cairo (RsvgHandle *handle, cairo_t *cr);
 
 /**
  * rsvg_handle_render_cairo_sub:
- * @handle: A #RsvgHandle
+ * @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.
+ * @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.
  *
  * Renders a single SVG element in the same place as for a whole SVG document (a "subset"
  * of the document).  Please try to use rsvg_handle_render_layer() instead, which allows
@@ -112,52 +105,45 @@ gboolean rsvg_handle_render_cairo (RsvgHandle *handle, cairo_t *cr);
  * Historically this function has picked a size for the whole document by itself, based
  * on the following rules:
  *
- * <itemizedlist>
- *   <listitem>
- *     If the SVG document has both <literal>width</literal> and <literal>height</literal>
- *     attributes with physical units (px, in, cm, mm, pt, pc) or font-based units (em,
- *     ex), the function computes the size directly based on the dots-per-inch (DPI) you
- *     have configured with rsvg_handle_set_dpi().  This is the same approach as
- *     rsvg_handle_get_intrinsic_size_in_pixels().
- *   </listitem>
- *   <listitem>
- *     Otherwise, if there is a <literal>viewBox</literal> attribute and both
- *     <literal>width</literal> and <literal>height</literal> are set to
- *     <literal>100%</literal> (or if they don't exist at all and thus default to 100%),
- *     the function uses the width and height of the viewBox as a pixel size.  This
- *     produces a rendered document with the correct aspect ratio.
- *   </listitem>
- *   <listitem>
- *     Otherwise, this function computes the extents of every graphical object in the SVG
- *     document to find the total extents.  This is moderately expensive, but no more expensive
- *     than rendering the whole document, for example.
- *   </listitem>
- *   <listitem>
- *     This function cannot deal with percentage-based units for <literal>width</literal>
- *     and <literal>height</literal> because there is no viewport against which they could
- *     be resolved; that is why it will compute the extents of objects in that case.  This
- *     is why we recommend that you use rsvg_handle_render_layer() instead, which takes
- *     in a viewport and follows the sizing policy from the web platform.
- *   </listitem>
- * </itemizedlist>
+ * * If the SVG document has both `width` and `height`
+ *   attributes with physical units (px, in, cm, mm, pt, pc) or font-based units (em,
+ *   ex), the function computes the size directly based on the dots-per-inch (DPI) you
+ *   have configured with rsvg_handle_set_dpi().  This is the same approach as
+ *   rsvg_handle_get_intrinsic_size_in_pixels().
+ *
+ * * Otherwise, if there is a `viewBox` attribute and both
+ *   `width` and `height` are set to
+ *   `100%` (or if they don't exist at all and thus default to 100%),
+ *   the function uses the width and height of the `viewBox` as a pixel size.  This
+ *   produces a rendered document with the correct aspect ratio.
+ *
+ * * Otherwise, this function computes the extents of every graphical object in the SVG
+ *   document to find the total extents.  This is moderately expensive, but no more expensive
+ *   than rendering the whole document, for example.
+ *
+ * * This function cannot deal with percentage-based units for `width`
+ *   and `height` because there is no viewport against which they could
+ *   be resolved; that is why it will compute the extents of objects in that case.  This
+ *   is why we recommend that you use rsvg_handle_render_layer() instead, which takes
+ *   in a viewport and follows the sizing policy from the web platform.
  *
  * 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
+ * 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
+ * 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.
+ * `#foo` (hash `foo`) to get the geometry of the element that
+ * has an `id="foo"` attribute.
  *
- * Returns: %TRUE if drawing succeeded; %FALSE otherwise.
+ * Returns: `TRUE` if drawing succeeded; `FALSE` otherwise.
  * Since: 2.14
  *
  * Deprecated: 2.52.  Please use rsvg_handle_render_layer() instead; that function lets
@@ -168,21 +154,21 @@ gboolean rsvg_handle_render_cairo_sub (RsvgHandle *handle, cairo_t *cr, const ch
 
 /**
  * rsvg_handle_render_document:
- * @handle: An #RsvgHandle
+ * @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
+ * @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 document is scaled proportionally to fit into this viewport.
  *
- * The @cr must be in a #CAIRO_STATUS_SUCCESS state, or this function will not
+ * 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="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.
  *
@@ -196,25 +182,25 @@ gboolean rsvg_handle_render_document (RsvgHandle           *handle,
 
 /**
  * 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
+ * @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
+ * @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.
+ * `#foo` (hash `foo`) to get the geometry of the element that
+ * has an `id="foo"` attribute.
  *
  * The "ink rectangle" is the bounding box that would be painted
- * for fully- stroked and filled elements.
+ * for fully-stroked and filled elements.
  *
  * The "logical rectangle" just takes into account the unstroked
  * paths and text outlines.
@@ -222,7 +208,7 @@ gboolean rsvg_handle_render_document (RsvgHandle           *handle,
  * 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
+ * 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.
  *
@@ -230,7 +216,7 @@ gboolean rsvg_handle_render_document (RsvgHandle           *handle,
  * the child elements.
  *
  * 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.
  *
@@ -246,13 +232,13 @@ gboolean rsvg_handle_get_geometry_for_layer (RsvgHandle     *handle,
 
 /**
  * rsvg_handle_render_layer:
- * @handle: An #RsvgHandle
+ * @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.
+ * @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
+ * @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.
  *
@@ -268,15 +254,15 @@ gboolean rsvg_handle_get_geometry_for_layer (RsvgHandle     *handle,
  * 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.
+ * `#foo` (hash `foo`) to get the geometry of the element that
+ * has an `id="foo"` attribute.
  *
- * You can pass #NULL for the @id if you want to render all
+ * 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="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.
  *
@@ -291,14 +277,14 @@ gboolean rsvg_handle_render_layer (RsvgHandle           *handle,
 
 /**
  * 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
+ * @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
+ * @error: (optional): a location to store a `GError`, or `NULL`
  *
  * Computes the ink rectangle and logical rectangle of a single SVG element.
  *
@@ -310,8 +296,8 @@ gboolean rsvg_handle_render_layer (RsvgHandle           *handle,
  * 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.
+ * `#foo` (hash `foo`) to get the geometry of the element that
+ * has an `id="foo"` attribute.
  *
  * The "ink rectangle" is the bounding box that would be painted
  * for fully- stroked and filled elements.
@@ -322,7 +308,7 @@ gboolean rsvg_handle_render_layer (RsvgHandle           *handle,
  * 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
+ * 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.
  *
@@ -330,7 +316,7 @@ gboolean rsvg_handle_render_layer (RsvgHandle           *handle,
  * the child elements.
  *
  * 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.
  *
@@ -345,15 +331,15 @@ gboolean rsvg_handle_get_geometry_for_element (RsvgHandle     *handle,
 
 /**
  * rsvg_handle_render_element:
- * @handle: An #RsvgHandle
+ * @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.
+ * @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
+ * @error: (optional): a location to store a `GError`, or `NULL`
  *
- * Renders a single SVG element to a given viewport
+ * 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
@@ -361,10 +347,10 @@ gboolean rsvg_handle_get_geometry_for_element (RsvgHandle     *handle,
  * 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.
+ * `#foo` (hash `foo`) to get the geometry of the element that
+ * has an `id="foo"` attribute.
  *
- * You can pass #NULL for the @id if you want to render all
+ * 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.
  *
@@ -372,7 +358,7 @@ gboolean rsvg_handle_get_geometry_for_element (RsvgHandle     *handle,
  * be rendered.  FIXME: mention proportional scaling.
  *
  * 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.
  *
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]