docs: Convert markup and attributes docs to pango_markup.md

6 files changed, 186 insertions, 503 deletions

diff --git a/docs/meson.build b/docs/meson.build
index bdea5e50..4e2c06e8 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -2,6 +2,7 @@ gidocgen = find_program('gi-docgen', required: get_option('gtk_doc'))
 
 pango_content_files = [
   'pango_rendering.md',
+  'pango_markup.md',
   'pango-name.png',
   'layout.png',
   'pipeline.png',
diff --git a/docs/pango.toml.in b/docs/pango.toml.in
index 2a0dbcc0..1e8c0048 100644
--- a/docs/pango.toml.in
+++ b/docs/pango.toml.in
@@ -56,6 +56,7 @@ base_url = "https://gitlab.gnome.org/GNOME/pango/-/blob/master/"
 [extra]
 content_files = [
   "pango_rendering.md",
+  "pango_markup.md",
 ]
 
 content_images = [
diff --git a/docs/pango_markup.md b/docs/pango_markup.md
new file mode 100644
index 00000000..dc6047d3
--- /dev/null
+++ b/docs/pango_markup.md
@@ -0,0 +1,184 @@
+---
+Title: Text Attributes and Markup
+---
+
+# Text Attributes
+
+Attributed text is used in a number of places in Pango. It is used as the
+input to the itemization process and also when creating a [class@Pango.Layout].
+
+Attributes can influence the various stages of the rendering pipeline. For example,
+font or size attributes will influence the font selection that is happening during
+itemization, font features and letterspacing attributes will influence shaping, and
+color or underline attributes will be used for rendering.
+
+Pango uses a simple structs for individual attributes, such as
+[struct@Pango.AttrColor] or [struct@Pango.AttrFontDesc]. Each attribute has a type,
+and a start and end index that determine the range of characters that the attribute
+applies to. See the [enum@Pango.AttrType] enumeration for all the possible
+attribute types.
+
+Attributes rarely come alone. Pango uses the [struct@Pango.AttrList] structure
+to hold all attributes that apply to a piece of text.
+
+# Pango Markup
+
+Frequently, you want to display some text to the user with attributes applied to
+part of the text (for example, you might want bold or italicized words). With the
+base Pango interfaces, you could create a [struct@Pango.AttrList] and apply it to
+the text; the problem is that you'd need to apply attributes to some numeric range
+of characters, for example "characters 12-17." This is broken from an
+internationalization standpoint; once the text is translated, the word you wanted
+to italicize could be in a different position.
+
+The solution is to include the text attributes in the string to be translated.
+Pango provides this feature with a small markup language. You can parse a marked-up
+string into the string text plus a [struct@Pango.AttrList] using either of
+[func@parse_markup] or [func@markup_parser_new].
+
+A simple example of a marked-up string might be:
+
+```
+<span foreground="blue" size="x-large">Blue text</span> is <i>cool</i>!"
+```
+
+Pango uses GMarkup to parse this language, which means that XML features
+such as numeric character entities such as `&#169;` for © can be used too.
+
+The root tag of a marked-up document is `<markup>`, but pango_parse_markup()
+allows you to omit this tag, so you will most likely never need to use it.
+The most general markup tag is `<span>`, then there are some convenience
+tags.
+
+## The `<span>` Attributes
+
+font
+font_desc
+: A font description string, such as "Sans Italic 12". See
+  pango_font_description_from_string() for a description of the format of
+  the string representation. Note that any other span attributes will override
+  this description. So if you have "Sans Italic" and also a style="normal"
+  attribute, you will get Sans normal, not italic.
+
+font_family
+face
+: A font family name.
+
+font_size
+size
+: Font size in 1024ths of a point, or one of the absolute sizes 'xx-small',
+  'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large', or one of the
+  relative sizes 'smaller' or 'larger'. If you want to specify a absolute size,
+  it's usually easier to take advantage of the ability to specify a partial font
+  description using 'font'; you can use font='12.5' rather than size='12800'.
+
+font_style
+style
+: One of 'normal', 'oblique', 'italic'.
+
+font_weight
+weight
+: One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a
+  numeric weight.
+
+font_variant
+variant
+: One of 'normal' or 'smallcaps'.
+
+font_stretch
+stretch
+: One of 'ultracondensed', 'extracondensed',
+  'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded',
+  'extraexpanded', 'ultraexpanded'.
+
+font_features
+: A comma-separated list of OpenType font feature settings, in the same syntax as
+  accepted by CSS. E.g: `font_features='dlig=1, -kern, afrc on'`.
+
+foreground
+fgcolor
+color
+: An RGB color specification such as '#00FF00' or a color name such as 'red'.
+  Since 1.38, an RGBA color specification such as '#00FF007F' will be interpreted
+  as specifying both a foreground color and foreground alpha.
+
+background
+bgcolor
+: An RGB color specification such as '#00FF00' or a color name such as 'red'.
+  Since 1.38, an RGBA color specification such as '#00FF007F' will be interpreted
+  as specifying both a background color and background alpha.
+
+alpha
+fgalpha
+: An alpha value for the foreground color, either a plain integer between 1 and
+  65536 or a percentage value like '50%'.
+
+background_alpha
+bgalpha
+: An alpha value for the background color, either a plain integer between 1 and
+  65536 or a percentage value like '50%'.
+
+underline
+: One of 'none', 'single', 'double', 'low', 'error'.
+
+underline_color
+: The color of underlines; an RGB color specification such as '#00FF00' or a color
+  name such as 'red'.
+
+rise
+: Vertical displacement, in Pango units. Can be negative for subscript, positive
+  for superscript.
+
+strikethrough
+: 'true' or 'false' whether to strike through the text.
+
+strikethrough_color
+: The color of strikethrough lines; an RGB color specification such as '#00FF00'
+  or a color name such as 'red'.
+
+fallback
+: 'true' or 'false' whether to enable fallback. If disabled, then characters will
+  only be used from the closest matching font on the system. No fallback will be
+  done to other fonts on the system that might contain the characters in the text.
+  Fallback is enabled by default. Most applications should not disable fallback.
+
+lang
+: A language code, indicating the text language.
+
+letter_spacing
+: Inter-letter spacing in 1024ths of a point.
+
+gravity
+: One of 'south', 'east', 'north', 'west', 'auto'.
+
+gravity_hint
+: One of 'natural', 'strong', 'line'.
+
+## Convenience Tags
+
+`<b>`
+: Bold
+
+`<big>`
+: Makes font relatively larger, equivalent to `<span size="larger">`
+
+`<i>`
+: Italic
+
+`<s>`
+: Strikethrough
+
+`<sub>`
+: Subscript
+
+`<sup>`
+: Superscript
+
+`<small>`
+: Makes font relatively smaller, equivalent to `<span size="smaller">`
+
+`<tt>`
+: Monospace font
+
+`<u>`
+: Underline
diff --git a/docs/pango_markup.sgml b/docs/pango_markup.sgml
deleted file mode 100644
index c2ba377c..00000000
--- a/docs/pango_markup.sgml
+++ /dev/null
@@ -1,301 +0,0 @@
-<refentry id="PangoMarkupFormat" revision="11 Dec 2002">
-<refmeta>
-<refentrytitle>Text Attribute Markup</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>Pango Library</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>Text Attribute Markup</refname><refpurpose>Simple
-markup language to encode text with attributes</refpurpose>
-</refnamediv>
-
-<refsect1 id="PangoMarkupFormatLanguage">
-<title>Pango Text Attribute Markup Language</title>
-
-<para>
-Frequently, you want to display some text to the user with attributes
-applied to part of the text (for example, you might want bold or
-italicized words). With the base Pango interfaces, you could create a
-<link linkend="PangoAttrList">PangoAttrList</link> and apply it to the
-text; the problem is that you'd need to apply attributes to some
-numeric range of characters, for example "characters 12-17." This is
-broken from an internationalization standpoint; once the text is
-translated, the word you wanted to italicize could be in a different
-position.
-</para>
-
-<para>
-The solution is to include the text attributes in the string to be
-translated. Pango provides this feature with a small markup language.
-You can parse a marked-up string into the string text plus a
-<link linkend="PangoAttrList">PangoAttrList</link> using either of
-<link linkend="pango-parse-markup">pango_parse_markup()</link> or
-<link linkend="pango-markup-parser-new">pango_markup_parser_new()</link>.
-</para>
-
-<para>
-A simple example of a marked-up string might be:
-<literal>"&lt;span foreground="blue" size="x-large"&gt;Blue text&lt;/span&gt; is &lt;i&gt;cool&lt;/i&gt;!"</literal>
-</para>
-
-<para>
-Pango uses #GMarkup to parse this language, which means that XML features
-such as numeric character entities such as &amp;#169; for &#169; can
-be used too.
-</para>
-
-<para>
-The root tag of a marked-up document is &lt;markup&gt;, but <link
-linkend="pango-parse-markup">pango_parse_markup()</link> allows you to
-omit this tag, so you will most likely never need to use it. The most
-general markup tag is &lt;span&gt;, then there are some convenience
-tags. &lt;span&gt; has the following attributes:
-<variablelist><title>&lt;span&gt; attributes</title>
-
-<varlistentry>
-<term>font<footnote id='since_1_21'><para>Since 1.21</para></footnote></term>
-<term>font_desc</term>
-<listitem><para>
-A font description string, such as "Sans Italic 12". See
-<link linkend="pango-font-description-from-string">pango_font_description_from_string()</link>
-for a description of the format of the string representation . Note that any 
-other span attributes will override this description. So if you have 
-"Sans Italic" and also a style="normal" attribute, you will get Sans normal, 
-not italic.</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>font_family</term>
-<term>face</term>
-<listitem><para>
-A font family name
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>font_size<footnoteref linkend='since_1_21'/></term>
-<term>size</term>
-<listitem><para>
-Font size in 1024ths of a point, or one of the absolute sizes 
-'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large',
-'xx-large', or one of the relative sizes 'smaller' or 'larger'.
-If you want to specify a absolute size, it's usually easier
-to take advantage of the ability to specify a partial
-font description using 'font'; you can use
-<literal>font='12.5'</literal> rather than
-<literal>size='12800'</literal>.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>font_style<footnoteref linkend='since_1_21'/></term>
-<term>style</term>
-<listitem><para>
-One of 'normal', 'oblique', 'italic'
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>font_weight<footnoteref linkend='since_1_21'/></term>
-<term>weight</term>
-<listitem><para>
-One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy',
-or a numeric weight
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>font_variant<footnoteref linkend='since_1_21'/></term>
-<term>variant</term>
-<listitem><para>
-One of 'normal' or 'smallcaps'
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>font_stretch<footnoteref linkend='since_1_21'/></term>
-<term>stretch</term>
-<listitem><para>
-One of 'ultracondensed', 'extracondensed', 'condensed',
-'semicondensed', 'normal', 'semiexpanded', 'expanded',
-'extraexpanded', 'ultraexpanded'
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>font_features<footnote id='since_1_38'><para>Since 1.38</para></footnote></term>
-<listitem><para>
-A comma separated list of OpenType font feature settings, in the same
-syntax as accepted by CSS. E.g: <literal>font_features='dlig=1, -kern, afrc on'</literal>
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>foreground</term>
-<term>fgcolor<footnoteref linkend='since_1_21'/></term>
-<term>color</term>
-<listitem><para>
-An RGB color specification such as '#00FF00' or a color name such as
-'red'.
-Since 1.38, an RGBA color specification such as '#00FF007F' will
-be interpreted as specifying both a foreground color and foreground alpha.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>background</term>
-<term>bgcolor<footnoteref linkend='since_1_21'/></term>
-<listitem><para>
-An RGB color specification such as '#00FF00' or a color name such as
-'red'.
-Since 1.38, an RGBA color specification such as '#00FF007F' will
-be interpreted as specifying both a background color and background alpha.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>alpha</term>
-<term>fgalpha<footnoteref linkend='since_1_38'/></term>
-<listitem><para>
-An alpha value for the foreground color, either a plain integer between 1 and 65536
-or a percentage value like '50%'.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>background_alpha</term>
-<term>bgalpha<footnoteref linkend='since_1_38'/></term>
-<listitem><para>
-An alpha value for the background color, either a plain integer between 1 and 65536
-or a percentage value like '50%'.
-</para></listitem>
-</varlistentry>
-
-<varlistentry><term>underline</term>
-<listitem><para>
-One of 'none', 'single', 'double', 'low', 'error'
-</para></listitem>
-</varlistentry>
-
-<varlistentry><term>underline_color</term>
-<listitem><para>
-The color of underlines; an RGB color specification such as '#00FF00'
-or a color name such as 'red'
-</para></listitem>
-</varlistentry>
-
-<varlistentry><term>rise</term>
-<listitem><para>
-Vertical displacement, in Pango units. Can be negative for 
-subscript, positive for superscript.
-</para></listitem>
-</varlistentry>
-
-<varlistentry><term>strikethrough</term>
-<listitem><para>
-'true' or 'false' whether to strike through the text
-</para></listitem>
-</varlistentry>
-
-<varlistentry><term>strikethrough_color</term>
-<listitem><para>
-The color of strikethrough lines; an RGB color specification such as
-'#00FF00' or a color name such as 'red'
-</para></listitem>
-</varlistentry>
-
-<varlistentry><term>fallback</term>
-<listitem><para>
-'true' or 'false' whether to enable fallback. If disabled, then characters
-will only be used from the closest matching font on the system. No fallback
-will be done to other fonts on the system that might contain the characters
-in the text.  Fallback is enabled by default. Most applications should not
-disable fallback.
-</para></listitem>
-</varlistentry>
-
-<varlistentry><term>lang</term>
-<listitem><para>
-A language code, indicating the text language
-</para></listitem>
-</varlistentry>
-
-<varlistentry><term>letter_spacing</term>
-<listitem><para>
-Inter-letter spacing in 1024ths of a point.
-</para></listitem>
-</varlistentry>
-
-<varlistentry><term>gravity</term>
-<listitem><para>
-One of 'south', 'east', 'north', 'west', 'auto'.
-</para></listitem>
-</varlistentry>
-
-<varlistentry><term>gravity_hint</term>
-<listitem><para>
-One of 'natural', 'strong', 'line'.
-</para></listitem>
-</varlistentry>
-
-</variablelist>
-
-</para>
-
-<para>
-The following convenience tags are provided:
-
-<variablelist><title>Convenience tags</title>
-<varlistentry><term>b</term>
-<listitem><para>
-Bold
-</para></listitem>
-</varlistentry>
-<varlistentry><term>big</term>
-<listitem><para>
-Makes font relatively larger, equivalent to &lt;span size="larger"&gt;
-</para></listitem>
-</varlistentry>
-<varlistentry><term>i</term>
-<listitem><para>
-Italic
-</para></listitem>
-</varlistentry>
-<varlistentry><term>s</term>
-<listitem><para>
-Strikethrough
-</para></listitem>
-</varlistentry>
-<varlistentry><term>sub</term>
-<listitem><para>
-Subscript
-</para></listitem>
-</varlistentry>
-<varlistentry><term>sup</term>
-<listitem><para>
-Superscript
-</para></listitem>
-</varlistentry>
-<varlistentry><term>small</term>
-<listitem><para>
-Makes font relatively smaller, equivalent to &lt;span size="smaller"&gt;
-</para></listitem>
-</varlistentry>
-<varlistentry><term>tt</term>
-<listitem><para>
-Monospace font
-</para></listitem>
-</varlistentry>
-<varlistentry><term>u</term>
-<listitem><para>
-Underline
-</para></listitem>
-</varlistentry>
-</variablelist>
-
-</para>
-
-</refsect1>
-
-</refentry>
diff --git a/pango/pango-attributes.c b/pango/pango-attributes.c
index 49226da5..85640b34 100644
--- a/pango/pango-attributes.c
+++ b/pango/pango-attributes.c
@@ -19,17 +19,6 @@
  * Boston, MA 02111-1307, USA.
  */
 
-/**
- * SECTION:text-attributes
- * @short_description:Font and other attributes for annotating text
- * @title:Attributes
- *
- * Attributed text is used in a number of places in Pango. It
- * is used as the input to the itemization process and also when
- * creating a #PangoLayout. The data types and functions in
- * this section are used to represent and manipulate sets
- * of attributes applied to a portion of text.
- */
 #include "config.h"
 #include <string.h>
 
diff --git a/pango/pango-markup.c b/pango/pango-markup.c
index 1c074fd6..08d202a5 100644
--- a/pango/pango-markup.c
+++ b/pango/pango-markup.c
@@ -30,197 +30,6 @@
 #include "pango-impl-utils.h"
 #include "pango-utils-internal.h"
 
-/**
- * SECTION:markup
- * @title:Markup
- * @short_description:Simple markup language for text with attributes
- *
- * Frequently, you want to display some text to the user with attributes
- * applied to part of the text (for example, you might want bold or
- * italicized words). With the base Pango interfaces, you could create a
- * #PangoAttrList and apply it to the text; the problem is that you'd
- * need to apply attributes to some numeric range of characters, for
- * example "characters 12-17." This is broken from an internationalization
- * standpoint; once the text is translated, the word you wanted to
- * italicize could be in a different position.
- *
- * The solution is to include the text attributes in the string to be
- * translated. Pango provides this feature with a small markup language.
- * You can parse a marked-up string into the string text plus a
- * #PangoAttrList using either of pango_parse_markup() or
- * pango_markup_parser_new().
- *
- * A simple example of a marked-up string might be:
- * ```
- * <span foreground="blue" size="x-large">Blue text</span> is <i>cool</i>!
- * ```
- *
- * Pango uses #GMarkup to parse this language, which means that XML
- * features such as numeric character entities such as `&#169;` for
- * © can be used too.
- *
- * The root tag of a marked-up document is `<markup>`, but
- * pango_parse_markup() allows you to omit this tag, so you will most
- * likely never need to use it. The most general markup tag is `<span>`,
- * then there are some convenience tags.
- *
- * ## Span attributes
- *
- * `<span>` has the following attributes:
- *
- * * `font_desc`:
- *   A font description string, such as "Sans Italic 12".
- *   See pango_font_description_from_string() for a description of the
- *   format of the string representation . Note that any other span
- *   attributes will override this description. So if you have "Sans Italic"
- *   and also a `style="normal"` attribute, you will get Sans normal,
- *   not italic.
- *
- * * `font_family`:
- *   A font family name
- *
- * * `font_size`, `size`:
- *   Font size in 1024ths of a point, or one of the absolute
- *   sizes `xx-small`, `x-small`, `small`, `medium`, `large`,
- *   `x-large`, `xx-large`, or one of the relative sizes `smaller`
- *   or `larger`. If you want to specify a absolute size, it's usually
- *   easier to take advantage of the ability to specify a partial
- *   font description using `font`; you can use `font='12.5'`
- *   rather than `size='12800'`.
- *
- * * `font_style`:
- *   One of `normal`, `oblique`, `italic`
- *
- * * `font_weight`:
- *   One of `ultralight`, `light`, `normal`, `bold`,
- *   `ultrabold`, `heavy`, or a numeric weight
- *
- * * `font_variant`:
- *   One of `normal` or `smallcaps`
- *
- * * `font_stretch`, `stretch`:
- *   One of `ultracondensed`, `extracondensed`, `condensed`,
- *   `semicondensed`, `normal`, `semiexpanded`, `expanded`,
- *   `extraexpanded`, `ultraexpanded`
- *
- * * `font_features`:
- *   A comma-separated list of OpenType font feature
- *   settings, in the same syntax as accepted by CSS. E.g:
- *   `font_features='dlig=1, -kern, afrc on'`
- *
- * * `foreground`, `fgcolor`:
- *   An RGB color specification such as `#00FF00` or a color
- *   name such as `red`. Since 1.38, an RGBA color specification such
- *   as `#00FF007F` will be interpreted as specifying both a foreground
- *   color and foreground alpha.
- *
- * * `background`, `bgcolor`:
- *   An RGB color specification such as `#00FF00` or a color
- *   name such as `red`.
- *   Since 1.38, an RGBA color specification such as `#00FF007F` will
- *   be interpreted as specifying both a background color and
- *   background alpha.
- *
- * * `alpha`, `fgalpha`:
- *   An alpha value for the foreground color, either a plain
- *   integer between 1 and 65536 or a percentage value like `50%`.
- *
- * * `background_alpha`, `bgalpha`:
- *   An alpha value for the background color, either a plain
- *   integer between 1 and 65536 or a percentage value like `50%`.
- *
- * * `underline`:
- *   One of `none`, `single`, `double`, `low`, `error`,
- *   `single-line`, `double-line` or `error-line`.
- *
- * * `underline_color`:
- *   The color of underlines; an RGB color
- *   specification such as `#00FF00` or a color name such as `red`
- *
- * * `overline`:
- *   One of `none` or `single`
- *
- * * `overline_color`:
- *   The color of overlines; an RGB color
- *   specification such as `#00FF00` or a color name such as `red`
- *
- * * `rise`:
- *   Vertical displacement, in Pango units. Can be negative for
- *   subscript, positive for superscript.
- *
- * * `strikethrough`
- *   `true` or `false` whether to strike through the text
- *
- * * `strikethrough_color`:
- *   The color of strikethrough lines; an RGB
- *   color specification such as `#00FF00` or a color name such as `red`
- *
- * * `fallback`:
- *   `true` or `false` whether to enable fallback. If
- *   disabled, then characters will only be used from the closest
- *   matching font on the system. No fallback will be done to other
- *   fonts on the system that might contain the characters in the text.
- *   Fallback is enabled by default. Most applications should not
- *   disable fallback.
- *
- * * `allow_breaks`:
- *   `true` or `false` whether to allow line breaks or not. If
- *   not allowed, the range will be kept in a single run as far
- *   as possible. Breaks are allowed by default.
- *
- * * `insert_hyphens`:`
- *   `true` or `false` whether to insert hyphens when breaking
- *   lines in the middle of a word. Hyphens are inserted by default.
- *
- * * `show`:
- *   A value determining how invisible characters are treated.
- *   Possible values are `spaces`, `line-breaks`, `ignorables`
- *   or combinations, such as `spaces|line-breaks`.
- *
- * * `lang`:
- *   A language code, indicating the text language
- *
- * * `letter_spacing`:
- *   Inter-letter spacing in 1024ths of a point.
- *
- * * `gravity`:
- *   One of `south`, `east`, `north`, `west`, `auto`.
- *
- * * `gravity_hint`:
- *   One of `natural`, `strong`, `line`.
- *
- * ## Convenience tags
- *
- * The following convenience tags are provided:
- *
- * * `<b>`:
- *   Bold
- *
- * * `<big>`:
- *   Makes font relatively larger, equivalent to `<span size="larger">`
- *
- * * `<i>`:
- *   Italic
- *
- * * `<s>`:
- *   Strikethrough
- *
- * * `<sub>`:
- *   Subscript
- *
- * * `<sup>`:
- *   Superscript
- *
- * * `<small>`:
- *   Makes font relatively smaller, equivalent to `<span size="smaller">`
- *
- * * `<tt>`:
- *   Monospace
- *
- * * `<u>`:
- *   Underline
- */
-
 /* FIXME */
 #define _(x) x