[pango/gi-docs: 23/43] docs: Convert more long descriptions

[Matthias Clasen <matthiasc src gnome org>]

commit 948e0810369a6c7ec4886e07b2ed9cccf10cb2c9
Author: Matthias Clasen <mclasen redhat com>
Date:   Thu Feb 4 22:51:04 2021 -0500

    docs: Convert more long descriptions
    
    Add markdown docs for fonts, bidi and vertical text.

 docs/pango.toml     |   5 ++++-
 docs/pango_bidi.md  |  55 ++++++++++++++++++++++++++++++++++++++++++++++++++
 docs/pango_fonts.md |  57 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 docs/rects3.png     | Bin 0 -> 17137 bytes
 4 files changed, 116 insertions(+), 1 deletion(-)
---
diff --git a/docs/pango.toml b/docs/pango.toml
index efecfcb9..bb916203 100644
--- a/docs/pango.toml
+++ b/docs/pango.toml
@@ -56,11 +56,14 @@ base_url = "https://gitlab.gnome.org/GNOME/pango/-/blob/master/";
 [extra]
 content_files = [
   [ "pango_rendering.md", "The Rendering Pipeline" ],
+  [ "pango_fonts.md", "Fonts and Glyphs" ],
   [ "pango_markup.md", "Text Attributes and Markup" ],
+  [ "pango_bidi.md", "Bidirectional and Vertical Text" ],
 ]
 content_images = [
   'layout.png',
   'pipeline.png',
   'rects1.png',
-  'rects2.png'
+  'rects2.png',
+  'rects3.png'
 ]
diff --git a/docs/pango_bidi.md b/docs/pango_bidi.md
new file mode 100644
index 00000000..cc97f350
--- /dev/null
+++ b/docs/pango_bidi.md
@@ -0,0 +1,55 @@
+# Bidirectional Text
+
+Pango supports bidirectional text (like Arabic and Hebrew) automatically.
+Some applications however, need some help to correctly handle bidirectional text.
+
+The #PangoDirection type can be used with pango_context_set_base_dir() to
+instruct Pango about direction of text, though in most cases Pango detects
+that correctly and automatically. For application that need more direct
+control over bidirectional setting of text, Pango provides APIs such as
+pango_unichar_direction(), pango_find_base_dir(), pango_get_mirror_char()
+or pango_bidi_type_for_unichar().
+
+# Vertical Text
+
+Pango is not only capable of vertical text layout, it can handle mixed vertical
+and non-vertical text correctly. This section describes the types used for setting
+vertical text parameters.
+
+The way this is implemented is through the concept of *gravity*. Gravity of
+normal Latin text is south. A gravity value of east means that glyphs will be
+rotated ninety degrees counterclockwise. So, to render vertical text one needs
+to set the gravity and rotate the layout using the matrix machinery already in
+place. This has the huge advantage that most algorithms working on a #PangoLayout
+do not need any change as the assumption that lines run in the X direction and
+stack in the Y direction holds even for vertical text layouts.
+
+Applications should only need to set base gravity on #PangoContext in use, and
+let Pango decide the gravity assigned to each run of text. This automatically
+handles text with mixed scripts. A very common use is to set the context base
+gravity to auto using pango_context_set_base_gravity() and rotate the layout
+normally. Pango will make sure that Asian languages take the right form, while
+other scripts are rotated normally.
+
+The correct way to set gravity on a layout is to set it on the context
+associated with it using pango_context_set_base_gravity(). The context
+of a layout can be accessed using pango_layout_get_context(). The currently
+set base gravity of the context can be accessed using
+pango_context_get_base_gravity() and the *resolved* gravity of it using
+pango_context_get_gravity(). The resolved gravity is the same as the base
+gravity for the most part, except that if the base gravity is set to
+%PANGO_GRAVITY_AUTO, the resolved gravity will depend on the current matrix
+set on context, and is derived using pango_gravity_get_for_matrix().
+
+The next thing an application may want to set on the context is the
+*gravity hint*. A #PangoGravityHint instructs how different scripts should
+react to the set base gravity.
+
+Font descriptions have a gravity property too, that can be set using
+pango_font_description_set_gravity() and accessed using
+pango_font_description_get_gravity(). However, those are rarely useful
+from application code and are mainly used by #PangoLayout internally.
+
+Last but not least, one can create #PangoAttributes for gravity
+and gravity hint using pango_attr_gravity_new() and
+pango_attr_gravity_hint_new().
diff --git a/docs/pango_fonts.md b/docs/pango_fonts.md
new file mode 100644
index 00000000..023be36b
--- /dev/null
+++ b/docs/pango_fonts.md
@@ -0,0 +1,57 @@
+Pango supports a flexible architecture where a particular rendering architecture
+can supply an implementation of fonts. The PangoFont structure represents an
+abstract rendering-system-independent font. Pango provides routines to list
+available fonts, and to load a font matching a given description.
+
+Conceptually, Pango groups fonts into faces and families which are identified
+by a name. A *font face* provides the different sizes of a single font style.
+A *font family* provides the available styles of a font.
+
+As an example, "Helvetica" is a family, "Helvetica Bold" is a face of this
+family, and "Helvetica Bold 12pt" is a concrete font of this face.
+
+# Font Enumeration
+
+The central object for dealing with the available fonts on a system and caching
+loaded fonts is a PangoFontMap. An application typically uses a single font map.
+
+Since the font map depends on the rendering architecture in use, you'll need to
+use the backend function pango_cairo_font_map_get_default() to obtain the default
+fontmap. Depending on the platform, it will return a PangoCairoFcFontMap, a
+PangoCairoWin32FontMap or a PangoCairoCoreTextFontMap.
+
+Once you have a fontmap, you can enumerate the available font families with
+pango_font_map_list_familiies(). To enumerate the faces of a font family, use
+pango_font_family_list_faces().
+
+# Font Descriptions
+
+Since loading fonts uses system resources, Pango provides a way to describe
+a font without loading it. A #PangoFontDescription is a struct that contains
+enough information to load a concrete font with pango_font_map_load_font()
+or pango_context_load_font(). You can obtain a font description from a
+font face using pango_font_face_describe(), or by parsing a string such as
+
+    Helvetica Bold 12pt
+
+with pango_font_description_from_string().
+
+# Glyphs
+
+A font provides information about glyphs and how to position and render them.
+The Pango rendering pipeline uses this information to create a #PangoGlyphString,
+which contains the glyphs corresponding to the characters in the text and related
+information such as glyph positions and sizes, and clustering information (i.e.
+which glyphs correspond to which characters).
+
+![A glyph string](rects3.png)
+
+A glyph is identified by a PangoGlyph, which is a numeric ID. Note that glyph
+IDs are font-specific: the same character can be represented by diffferent glyph
+IDs in different fonts.
+
+The mapping between characters and glyphs is in general neither 1-1 nor a map:
+a single glyph may represent multiple characters (as is the case with ligatures),
+a single character may be represented by multiple glyphs (for example, when combining
+accents and base character), and in complex scripts, multiple characters may form
+clusters that get rearranged and represented by multiple glyphs.
diff --git a/docs/rects3.png b/docs/rects3.png
new file mode 100644
index 00000000..4817b7af
Binary files /dev/null and b/docs/rects3.png differ