[pango/gi-docs: 20/47] docs: Add a section on attributes

[Matthias Clasen <matthiasc src gnome org>]

commit b50a35779e7335469c9dfbae93b0b1c52a7c9d17
Author: Matthias Clasen <mclasen redhat com>
Date:   Thu Feb 4 21:53:25 2021 -0500

    docs: Add a section on attributes

 docs/pango.toml      |  2 +-
 docs/pango_markup.md | 27 ++++++++++++++++++++++++---
 2 files changed, 25 insertions(+), 4 deletions(-)
---
diff --git a/docs/pango.toml b/docs/pango.toml
index f34d7cfa..efecfcb9 100644
--- a/docs/pango.toml
+++ b/docs/pango.toml
@@ -56,7 +56,7 @@ base_url = "https://gitlab.gnome.org/GNOME/pango/-/blob/master/";
 [extra]
 content_files = [
   [ "pango_rendering.md", "The Rendering Pipeline" ],
-  [ "pango_markup.md", "Pango Markup" ],
+  [ "pango_markup.md", "Text Attributes and Markup" ],
 ]
 content_images = [
   'layout.png',
diff --git a/docs/pango_markup.md b/docs/pango_markup.md
index 0b571228..31d93883 100644
--- a/docs/pango_markup.md
+++ b/docs/pango_markup.md
@@ -1,3 +1,25 @@
+# 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 #PangoLayout.
+
+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
+#PangoAttrColor or #PangoAttrFontDesc. Each attribute has a type, and
+a start and end index that determine the range of characters that the
+attribute applies to. See the #PangoAttrType enumeration for all the
+possible attribute types.
+
+Attributes rarely come alone. Pango uses the #PangoAttrList 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
@@ -9,9 +31,8 @@ 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().
+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: