docs: Convert markup and attributes docs to pango_markup.md

1 files changed, 184 insertions, 0 deletions

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