[pango/gi-docs: 4/13] More gi-docgen conversion

[Matthias Clasen <matthiasc src gnome org>]

commit 6d885f7b217fd6f592a7d85e287db0a81f7a0804
Author: Matthias Clasen <mclasen redhat com>
Date:   Wed Feb 3 23:30:31 2021 -0500

    More gi-docgen conversion
    
    Convert the "rendering" long description to a
    standalone markdown section.

 docs/pango.toml         | 10 ++++++++--
 docs/pango_rendering.md | 28 ++++++++++++++++++++++++++++
 2 files changed, 36 insertions(+), 2 deletions(-)
---
diff --git a/docs/pango.toml b/docs/pango.toml
index 83e02ebc..6d77877f 100644
--- a/docs/pango.toml
+++ b/docs/pango.toml
@@ -7,8 +7,8 @@ website_url = "https://www.pango.org";
 authors = "Owen Taylor, Behdad Esfahbod"
 logo_url = "https://pango.gnome.org/ScriptGallery?action=AttachFile&do=get&target=pango-name.png";
 license = "GPL-2.1-or-later"
-description = "A library for laying out and rendering of text"
-dependencies = [ "GObject-2.0", "HarfBuzz-0.0", "fontconfig-2.0" ]
+description = "Internationalized text layout and rendering"
+dependencies = [ "GObject-2.0", "HarfBuzz-0.0", "cairo-1.0" ]
 
   [dependencies."GObject-2.0"]
   name = "GObject"
@@ -20,6 +20,11 @@ dependencies = [ "GObject-2.0", "HarfBuzz-0.0", "fontconfig-2.0" ]
   description = "A text shaping library"
   docs_url = "https://harfbuzz.github.io/";
 
+  [dependencies."cairo-1.0"]
+  name = "cairo"
+  description = "A vector graphics library"
+  docs_url = "https://www.cairographics.org/manual/";
+
 [theme]
 name = "basic"
 
@@ -29,4 +34,5 @@ base_url = "https://gitlab.gnome.org/GNOME/pango/-/blob/master/";
 [extra]
 content_files = [
   [ "pango_markup.md", "Pango Markup" ],
+  [ "pango_rendering.md", "Pango Rendering" ],
 ]
diff --git a/docs/pango_rendering.md b/docs/pango_rendering.md
new file mode 100644
index 00000000..a8fbd12b
--- /dev/null
+++ b/docs/pango_rendering.md
@@ -0,0 +1,28 @@
+
+# Pango Rendering
+
+The Pango rendering pipeline takes a string of Unicode characters and converts
+it into glyphs. This section describes the functions that implement the various
+stages of this pipeline.
+
+![Pango Rendering Pipeline](pipeline.png)
+
+* Itemization breaks a piece of text into segments with consistent direction
+  and shaping properies. Among other things, this determines which font to use
+  for each character. Use pango_itemize() or pango_itemize_with_base_dir()
+  to itemize text.
+
+* Shaping converts characters into glyphs. Use pango_shape(), pango_shape_full()
+  or pango_shape_with_flags() to shape text.
+
+* Line Breaking determines where line breaks should be inserted into a sequence
+  of glyphs. The function pango_break() determines possible line breaks. The
+  actual line breaking is done by PangoLayout.
+
+* Justification adjusts inter-word spacing to form lines of even length. This
+  is done by PangoLayout.
+
+* Rendering takes a string of positioned glyphs, and renders them onto a
+  surface. This is accomplished by a PangoRenderer object. The functions
+  pango_cairo_show_glyph_string() and pango_cairo_show_layout() use a
+  PangoRenderer to draw text onto a cairo surface.