[pango/gi-docs: 1/45] docs: Convert markup and attributes docs to pango_markup.md

[Matthias Clasen <matthiasc src gnome org>]

commit 776a5dfcb1d026ac0b635a68c7cd54ec12709ab7
Author: Matthias Clasen <mclasen redhat com>
Date:   Wed Feb 17 00:43:39 2021 -0500

    docs: Convert markup and attributes docs to pango_markup.md

 docs/meson.build         |   1 +
 docs/pango.toml.in       |   1 +
 docs/pango_markup.md     | 184 +++++++++++++++++++++++++++++
 docs/pango_markup.sgml   | 301 -----------------------------------------------
 pango/pango-attributes.c |  11 --
 pango/pango-markup.c     | 191 ------------------------------
 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/pango/pango-attributes.c b/pango/pango-attributes.c
index a545fa78..e62e1b5c 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 b3afcef5..a278409e 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