Revert "Fix leftover markup in docs"

This reverts commit 19a252d9a3d63e7816f9a77bab65bd161675440a.

8 files changed, 73 insertions, 69 deletions

diff --git a/pango/pango-attributes.c b/pango/pango-attributes.c
index 840621c4..9059b1de 100644
--- a/pango/pango-attributes.c
+++ b/pango/pango-attributes.c
@@ -1804,7 +1804,7 @@ pango_attr_iterator_get (PangoAttrIterator *iterator,
  *        pango_font_description_set_family_static() using values from
  *        an attribute in the #PangoAttrList associated with the iterator,
  *        so if you plan to keep it around, you must call:
- *        `pango_font_description_set_family (desc, pango_font_description_get_family (desc))`.
+ *        <literal>pango_font_description_set_family (desc, pango_font_description_get_family (desc))</literal>.
  * @language: (allow-none): if non-%NULL, location to store language tag for item, or %NULL
  *            if none is found.
  * @extra_attrs: (allow-none) (element-type Pango.Attribute) (transfer full): if non-%NULL,
diff --git a/pango/pango-color.c b/pango/pango-color.c
index 3f20b89e..e54eb0d3 100644
--- a/pango/pango-color.c
+++ b/pango/pango-color.c
@@ -79,7 +79,8 @@ pango_color_free (PangoColor *color)
  * @color: a #PangoColor
  *
  * Returns a textual specification of @color in the hexadecimal form
- * “\#rrrrggggbbbb”, where “r”, “g” and “b” are hex digits representing
+ * <literal>&num;rrrrggggbbbb</literal>, where <literal>r</literal>,
+ * <literal>g</literal> and <literal>b</literal> are hex digits representing
  * the red, green, and blue components respectively.
  *
  * Return value: a newly-allocated text string that must be freed with g_free().
diff --git a/pango/pango-engine.h b/pango/pango-engine.h
index 470c1eae..0b8abbe3 100644
--- a/pango/pango-engine.h
+++ b/pango/pango-engine.h
@@ -182,9 +182,10 @@ struct _PangoEngineShape
  *   appropriately using pango_glyph_string_set_size()). All fields
  *   of the @log_clusters and @glyphs array must be filled in, with
  *   the exception that Pango will automatically generate
- *   `glyphs->glyphs[i].attr.is_cluster_start` using the @log_clusters
- *   array. Each input character must occur in one of the output logical
- *   clusters; if no rendering is desired for a character, this may involve
+ *   <literal>glyphs->glyphs[i].attr.is_cluster_start</literal>
+ *   using the @log_clusters array. Each input character must occur in one
+ *   of the output logical clusters;
+ *   if no rendering is desired for a character, this may involve
  *   inserting glyphs with the #PangoGlyph ID #PANGO_GLYPH_EMPTY, which
  *   is guaranteed never to render. If the shaping fails for any reason,
  *   the shaper should return with an empty (zero-size) glyph string.
@@ -344,8 +345,8 @@ prefix ## _register_type (GTypeModule *module)				  \
 
 /**
  * PANGO_ENGINE_LANG_DEFINE_TYPE:
- * @name: Name of the the type to register (for example:, `ArabicEngineFc`)
- * @prefix: Prefix for symbols that will be defined (for example:, `arabic_engine_fc`)
+ * @name: Name of the the type to register (for example:, <literal>ArabicEngineFc</literal>
+ * @prefix: Prefix for symbols that will be defined (for example:, <literal>arabic_engine_fc</literal>
  * @class_init: Class initialization function for the new type, or %NULL
  * @instance_init: Instance initialization function for the new type, or %NULL
  *
@@ -353,19 +354,19 @@ prefix ## _register_type (GTypeModule *module)				  \
  * #PangoEngineLang class defined in a module. Two static symbols
  * are defined.
  *
- * |[<!-- language="C" -->
- *  static GType `prefix`_type;
- *  static void `prefix`_register_type (GTypeModule module);
- * ]|
+ * <programlisting>
+ *  static GType <replaceable>prefix</replaceable>_type;
+ *  static void <replaceable>prefix</replaceable>_register_type (GTypeModule module);
+ * </programlisting>
  *
- * The `prefix`_register_type() function should be called in your
- * script_engine_init() function for each type that your module implements,
- * and then your script_engine_create() function can create instances of the
- * object as follows:
+ * The <function><replaceable>prefix</replaceable>_register_type()</function>
+ * function should be called in your script_engine_init() function for
+ * each type that your module implements, and then your script_engine_create()
+ * function can create instances of the object as follows:
  *
- * |[<!-- language="C" -->
- *  PangoEngine *engine = g_object_new (`prefix`_type, NULL);
- * ]|
+ * <informalexample><programlisting>
+ *  PangoEngine *engine = g_object_new (<replaceable>prefix</replaceable>_type, NULL);
+ * </programlisting></informalexample>
  **/
 #define PANGO_ENGINE_LANG_DEFINE_TYPE(name, prefix, class_init, instance_init)	\
   PANGO_ENGINE_DEFINE_TYPE (name, prefix,				\
@@ -374,8 +375,8 @@ prefix ## _register_type (GTypeModule *module)				  \
 
 /**
  * PANGO_ENGINE_SHAPE_DEFINE_TYPE:
- * @name: Name of the the type to register (for example:, `ArabicEngineFc`)
- * @prefix: Prefix for symbols that will be defined (for example:, `arabic_engine_fc`)
+ * @name: Name of the the type to register (for example:, <literal>ArabicEngineFc</literal>
+ * @prefix: Prefix for symbols that will be defined (for example:, <literal>arabic_engine_fc</literal>
  * @class_init: Class initialization function for the new type, or %NULL
  * @instance_init: Instance initialization function for the new type, or %NULL
  *
@@ -383,19 +384,19 @@ prefix ## _register_type (GTypeModule *module)				  \
  * #PangoEngineShape class defined in a module. Two static symbols
  * are defined.
  *
- * |[<!-- language="C" -->
- *  static GType `prefix`_type;
- *  static void `prefix`_register_type (GTypeModule module);
- * ]|
+ * <programlisting>
+ *  static GType <replaceable>prefix</replaceable>_type;
+ *  static void <replaceable>prefix</replaceable>_register_type (GTypeModule module);
+ * </programlisting>
  *
- * The `prefix`_register_type() function should be called in your
- * script_engine_init() function for each type that your module implements,
- * and then your script_engine_create() function can create instances of the
- * object as follows:
+ * The <function><replaceable>prefix</replaceable>_register_type()</function>
+ * function should be called in your script_engine_init() function for
+ * each type that your module implements, and then your script_engine_create()
+ * function can create instances of the object as follows:
  *
- * |[<!-- language="C" -->
- *  PangoEngine *engine = g_object_new (`prefix`_type, NULL);
- * ]|
+ * <informalexample><programlisting>
+ *  PangoEngine *engine = g_object_new (<replaceable>prefix</replaceable>_type, NULL);
+ * </programlisting></informalexample>
  **/
 #define PANGO_ENGINE_SHAPE_DEFINE_TYPE(name, prefix, class_init, instance_init)	\
   PANGO_ENGINE_DEFINE_TYPE (name, prefix,				\
diff --git a/pango/pango-glyph-item.h b/pango/pango-glyph-item.h
index 529879ef..61b5ec47 100644
--- a/pango/pango-glyph-item.h
+++ b/pango/pango-glyph-item.h
@@ -79,7 +79,7 @@ void 	  pango_glyph_item_get_logical_widths (PangoGlyphItem *glyph_item,
  * #PangoGlyphItem.  The <firstterm>forward direction</firstterm> of the
  * iterator is the logical direction of text.  That is, with increasing
  * @start_index and @start_char values.  If @glyph_item is right-to-left
- * (that is, if `@glyph_item->item->analysis.level` is odd),
+ * (that is, if <literal>@glyph_item->item->analysis.level</literal> is odd),
  * then @start_glyph decreases as the iterator moves forward.  Moreover,
  * in right-to-left cases, @start_glyph is greater than @end_glyph.
  *
@@ -90,26 +90,26 @@ void 	  pango_glyph_item_get_logical_widths (PangoGlyphItem *glyph_item,
  * pango_glyph_item_iter_next_cluster() and
  * pango_glyph_item_iter_prev_cluster().  A common idiom for doing a
  * forward iteration over the clusters is:
- * |[<!-- language="C" -->
+ * <programlisting>
  * PangoGlyphItemIter cluster_iter;
  * gboolean have_cluster;
  *
- * for (have_cluster = pango_glyph_item_iter_init_start (&cluster_iter,
+ * for (have_cluster = pango_glyph_item_iter_init_start (&amp;cluster_iter,
  *                                                       glyph_item, text);
  *      have_cluster;
- *      have_cluster = pango_glyph_item_iter_next_cluster (&cluster_iter))
+ *      have_cluster = pango_glyph_item_iter_next_cluster (&amp;cluster_iter))
  * {
  *   ...
  * }
- * ]|
+ * </programlisting>
  *
  * Note that @text is the start of the text for layout, which is then
- * indexed by `@glyph_item->item->offset` to get to the text of @glyph_item.
- * The @start_index and @end_index values can directly index into @text. The
- * @start_glyph, @end_glyph, @start_char, and @end_char values however are
- * zero-based for the @glyph_item. For each cluster, the item pointed at by
- * the start variables is included in the cluster while the one pointed at
- * by end variables is not.
+ * indexed by <literal>@glyph_item->item->offset</literal> to get to the
+ * text of @glyph_item.  The @start_index and @end_index values can directly
+ * index into @text.  The @start_glyph, @end_glyph, @start_char, and @end_char
+ * values however are zero-based for the @glyph_item.  For each cluster, the
+ * item pointed at by the start variables is included in the cluster while
+ * the one pointed at by end variables is not.
  *
  * None of the members of a #PangoGlyphItemIter should be modified manually.
  *
diff --git a/pango/pango-language.c b/pango/pango-language.c
index fa7c1ba5..e9c9d1f4 100644
--- a/pango/pango-language.c
+++ b/pango/pango-language.c
@@ -151,7 +151,7 @@ G_DEFINE_BOXED_TYPE (PangoLanguage, pango_language,
  *
  * Return the Unix-style locale string for the language currently in
  * effect. On Unix systems, this is the return value from
- * `setlocale(LC_CTYPE, NULL)`, and the user can
+ * <literal>setlocale(LC_CTYPE, NULL)</literal>, and the user can
  * affect this through the environment variables LC_ALL, LC_CTYPE or
  * LANG (checked in that order). The locale strings typically is in
  * the form lang_COUNTRY, where lang is an ISO-639 language code, and
@@ -237,7 +237,7 @@ _pango_get_lc_ctype (void)
  * Note that this can change over the life of an application.
  *
  * On Unix systems, this is the return value is derived from
- * `setlocale(LC_CTYPE, NULL)`, and the user can
+ * <literal>setlocale(LC_CTYPE, NULL)</literal>, and the user can
  * affect this through the environment variables LC_ALL, LC_CTYPE or
  * LANG (checked in that order). The locale string typically is in
  * the form lang_COUNTRY, where lang is an ISO-639 language code, and
@@ -255,10 +255,10 @@ _pango_get_lc_ctype (void)
  * variables, and does return a Unix-style locale string based on
  * either said environment variables or the thread's current locale.
  *
- * Your application should call `setlocale(LC_ALL, "")` for the user
- * settings to take effect.  GTK+ does this in its initialization
+ * Your application should call <literal>setlocale(LC_ALL, "");</literal>
+ * for the user settings to take effect.  Gtk+ does this in its initialization
  * functions automatically (by calling gtk_set_locale()).
- * See `man setlocale` for more details.
+ * See <literal>man setlocale</literal> for more details.
  *
  * Return value: (transfer none): the default language as a
  *               #PangoLanguage, must not be freed.
@@ -819,24 +819,25 @@ out:
  * representative of that script. This will usually be the
  * most widely spoken or used language written in that script:
  * for instance, the sample language for %PANGO_SCRIPT_CYRILLIC
- * is `ru` (Russian), the sample language for %PANGO_SCRIPT_ARABIC
- * is `ar`.
- *
- * For some scripts, no sample language will be returned because
- * there is no language that is sufficiently representative. The
- * best example of this is %PANGO_SCRIPT_HAN, where various
- * different variants of written Chinese, Japanese, and Korean
- * all use significantly different sets of Han characters and
- * forms of shared characters. No sample language can be provided
+ * is <literal>ru</literal> (Russian), the sample language
+ * for %PANGO_SCRIPT_ARABIC is <literal>ar</literal>.
+ *
+ * For some
+ * scripts, no sample language will be returned because there
+ * is no language that is sufficiently representative. The best
+ * example of this is %PANGO_SCRIPT_HAN, where various different
+ * variants of written Chinese, Japanese, and Korean all use
+ * significantly different sets of Han characters and forms
+ * of shared characters. No sample language can be provided
  * for many historical scripts as well.
  *
  * As of 1.18, this function checks the environment variables
  * PANGO_LANGUAGE and LANGUAGE (checked in that order) first.
  * If one of them is set, it is parsed as a list of language tags
- * separated by colons or other separators. This function
+ * separated by colons or other separators.  This function
  * will return the first language in the parsed list that Pango
- * believes may use @script for writing. This last predicate
- * is tested using pango_language_includes_script(). This can
+ * believes may use @script for writing.  This last predicate
+ * is tested using pango_language_includes_script().  This can
  * be used to control Pango's font selection for non-primary
  * languages.  For example, a PANGO_LANGUAGE enviroment variable
  * set to "en:fa" makes Pango choose fonts suitable for Persian (fa) 
diff --git a/pango/pango-layout.c b/pango/pango-layout.c
index 44ddbbd3..607a5f0e 100644
--- a/pango/pango-layout.c
+++ b/pango/pango-layout.c
@@ -1525,7 +1525,7 @@ pango_layout_get_lines_readonly (PangoLayout *layout)
  * pango_layout_get_line:
  * @layout: a #PangoLayout
  * @line: the index of a line, which must be between 0 and
- *        `pango_layout_get_line_count(layout) - 1`, inclusive.
+ *        <literal>pango_layout_get_line_count(layout) - 1</literal>, inclusive.
  *
  * Retrieves a particular line from a #PangoLayout.
  *
@@ -1566,7 +1566,7 @@ pango_layout_get_line (PangoLayout *layout,
  * pango_layout_get_line_readonly:
  * @layout: a #PangoLayout
  * @line: the index of a line, which must be between 0 and
- *        `pango_layout_get_line_count(layout) - 1`, inclusive.
+ *        <literal>pango_layout_get_line_count(layout) - 1</literal>, inclusive.
  *
  * Retrieves a particular line from a #PangoLayout.
  *
@@ -2110,10 +2110,10 @@ pango_layout_xy_to_index (PangoLayout *layout,
  *
  * Converts from an index within a #PangoLayout to the onscreen position
  * corresponding to the grapheme at that index, which is represented
- * as rectangle.  Note that `@pos->x` is always the leading edge of the
- * grapheme and `@pos->x + @pos->width` the trailing edge of the grapheme.
- * If the directionality of the grapheme is right-to-left, then `@pos->width`
- * will be negative.
+ * as rectangle.  Note that <literal>pos->x</literal> is always the leading
+ * edge of the grapheme and <literal>pos->x + pos->width</literal> the trailing
+ * edge of the grapheme. If the directionality of the grapheme is right-to-left,
+ * then <literal>pos->width</literal> will be negative.
  **/
 void
 pango_layout_index_to_pos (PangoLayout    *layout,
@@ -4348,8 +4348,9 @@ pango_layout_line_get_width (PangoLayoutLine *line)
  *               trailing edge of the last character.
  * @ranges: (out) (array length=n_ranges) (transfer full):
  *               location to store a pointer to an array of ranges.
- *               The array will be of length `2*n_ranges`, with each range
- *               starting at `(*ranges)[2*n]` and of width `(*ranges)[2*n + 1] - (*ranges)[2*n]`.
+ *               The array will be of length <literal>2*n_ranges</literal>,
+ *               with each range starting at <literal>(*ranges)[2*n]</literal>
+ *               and of width <literal>(*ranges)[2*n + 1] - (*ranges)[2*n]</literal>.
  *               This array must be freed with g_free(). The coordinates are relative
  *               to the layout and are in Pango units.
  * @n_ranges: The number of ranges stored in @ranges.
diff --git a/pango/pango-renderer.c b/pango/pango-renderer.c
index e2c1f683..e30af474 100644
--- a/pango/pango-renderer.c
+++ b/pango/pango-renderer.c
@@ -684,7 +684,7 @@ pango_renderer_default_draw_glyphs (PangoRenderer    *renderer,
  * output format supports it (PDF for example).
  *
  * Note that @text is the start of the text for layout, which is then
- * indexed by `@glyph_item->item->offset`.
+ * indexed by <literal>@glyph_item->item->offset</literal>.
  *
  * If @text is %NULL, this simply calls pango_renderer_draw_glyphs().
  *
diff --git a/pango/pangocairo-render.c b/pango/pangocairo-render.c
index 0adc032c..03a2811a 100644
--- a/pango/pangocairo-render.c
+++ b/pango/pangocairo-render.c
@@ -1080,7 +1080,7 @@ pango_cairo_show_glyph_string (cairo_t          *cr,
  * be drawn at the current point of the cairo context.
  *
  * Note that @text is the start of the text for layout, which is then
- * indexed by `@glyph_item->item->offset`.
+ * indexed by <literal>@glyph_item->item->offset</literal>.
  *
  * Since: 1.22
  **/