[pango/gi-docs: 26/74] docs: Convert bidi and vertical sections to pango_bidi.md

[Matthias Clasen <matthiasc src gnome org>]

commit a56afbd216d8673e934c752b63b5b6c1469208a3
Author: Matthias Clasen <mclasen redhat com>
Date:   Wed Feb 17 01:10:49 2021 -0500

    docs: Convert bidi and vertical sections to pango_bidi.md

 docs/meson.build        |  1 +
 docs/pango.toml.in      |  1 +
 docs/pango_bidi.md      | 58 +++++++++++++++++++++++++++++++++++++++++++++++++
 pango/pango-bidi-type.c | 18 ---------------
 pango/pango-gravity.c   | 56 -----------------------------------------------
 5 files changed, 60 insertions(+), 74 deletions(-)
---
diff --git a/docs/meson.build b/docs/meson.build
index fdf49162..e5c4e350 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -4,6 +4,7 @@ pango_content_files = [
   'pango_rendering.md',
   'pango_markup.md',
   'pango_fonts.md',
+  'pango_bidi.md',
   'pango-name.png',
   'layout.png',
   'pipeline.png',
diff --git a/docs/pango.toml.in b/docs/pango.toml.in
index eca52ea2..1d3a1b43 100644
--- a/docs/pango.toml.in
+++ b/docs/pango.toml.in
@@ -58,6 +58,7 @@ content_files = [
   "pango_rendering.md",
   "pango_markup.md",
   "pango_fonts.md",
+  "pango_bidi.md",
 ]
 
 content_images = [
diff --git a/docs/pango_bidi.md b/docs/pango_bidi.md
new file mode 100644
index 00000000..12e75e38
--- /dev/null
+++ b/docs/pango_bidi.md
@@ -0,0 +1,58 @@
+---
+Title: Bidirectional and Vertical Text
+---
+
+# Bidirectional Text
+
+Pango supports bidirectional text (like Arabic and Hebrew) automatically.
+Some applications however, need some help to correctly handle bidirectional text.
+
+The [enum@Pango.Direction] type can be used with [method@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
+[func@unichar_direction], [func@find_base_dir], [func@get_mirror_char]
+or [func@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
+[class@Pango.Layout] 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 [class@Pango.Context] 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 [method@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 [method@Pango.Context.set_base_gravity]. The context of a layout can
+be accessed using [method@Pango.Layout.get_context]. The currently set base gravity
+of the context can be accessed using [method@Pango.Context.get_base_gravity] and the
+*resolved* gravity of it using [method@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 [func@gravity_get_for_matrix].
+
+The next thing an application may want to set on the context is the *gravity hint*.
+A [enum@Pango.GravityHint] instructs how different scripts should react to the set
+base gravity.
+
+Font descriptions have a gravity property too, that can be set using
+[method@Pango.FontDescription.set_gravity] and accessed using
+[method@Pango.FontDescription.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 [func@attr_gravity_new] and [func@attr_gravity_hint_new].
diff --git a/pango/pango-bidi-type.c b/pango/pango-bidi-type.c
index d4d84e03..0fc1c3e4 100644
--- a/pango/pango-bidi-type.c
+++ b/pango/pango-bidi-type.c
@@ -19,24 +19,6 @@
  * Boston, MA 02111-1307, USA.
  */
 
-/**
- * SECTION:bidi
- * @short_description:Types and functions for bidirectional text
- * @title:Bidirectional Text
- * @see_also:
- * pango_context_get_base_dir(),
- * pango_context_set_base_dir(),
- * pango_itemize_with_base_dir()
- *
- * 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.  The rest of the facilities in this section
- * are used internally by Pango already, and are provided to help applications
- * that need more direct control over bidirectional setting of text.
- */
 #include "config.h"
 
 #include <string.h>
diff --git a/pango/pango-gravity.c b/pango/pango-gravity.c
index 2d48c45e..ea6ef9e2 100644
--- a/pango/pango-gravity.c
+++ b/pango/pango-gravity.c
@@ -19,62 +19,6 @@
  * Boston, MA 02111-1307, USA.
  */
 
-/**
- * SECTION:vertical
- * @short_description:Laying text out in vertical directions
- * @title:Vertical Text
- * @see_also: pango_context_get_base_gravity(),
- * pango_context_set_base_gravity(),
- * pango_context_get_gravity(),
- * pango_context_get_gravity_hint(),
- * pango_context_set_gravity_hint(),
- * pango_font_description_set_gravity(),
- * pango_font_description_get_gravity(),
- * pango_attr_gravity_new(),
- * pango_attr_gravity_hint_new()
- *
- * Since 1.16, Pango is able to correctly lay vertical text out. In fact, it can
- * set layouts of mixed vertical and non-vertical text. 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().
- */
 #include "config.h"
 
 #include "pango-gravity.h"