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

[Matthias Clasen <matthiasc src gnome org>]

commit 854a506883a70e4b2d43eaa60e6ad3114a5f0f6a
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     |  2 ++
 docs/pango_bidi.md  | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 docs/pango_fonts.md | 35 ++++++++++++++++++++++++++++++++++
 3 files changed, 92 insertions(+)
---
diff --git a/docs/pango.toml b/docs/pango.toml
index efecfcb9..630f7b35 100644
--- a/docs/pango.toml
+++ b/docs/pango.toml
@@ -56,7 +56,9 @@ base_url = "https://gitlab.gnome.org/GNOME/pango/-/blob/master/";
 [extra]
 content_files = [
   [ "pango_rendering.md", "The Rendering Pipeline" ],
+  [ "pango_fonts.md", "Fonts" ],
   [ "pango_markup.md", "Text Attributes and Markup" ],
+  [ "pango_bidi.md", "Bidirectional and Vertical Text" ],
 ]
 content_images = [
   'layout.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..7109135f
--- /dev/null
+++ b/docs/pango_fonts.md
@@ -0,0 +1,35 @@
+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 backend functions such as pango_cairo_font_map_get_default() or
+pango_win32_gt_font_map_for_display() to obtain the fontmap.
+
+To enumerate the available font families, use 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().