Bug 685167 - migrate docs to no-tmpl flavour

Patch from Rafał Mużyło.

1 files changed, 59 insertions, 1 deletions

diff --git a/pango/pango-gravity.c b/pango/pango-gravity.c
index 603c3776..a72b67bc 100644
--- a/pango/pango-gravity.c
+++ b/pango/pango-gravity.c
@@ -19,6 +19,64 @@
  * 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
+ * <firstterm>gravity</firstterm>.  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 <firstterm>resolved</firstterm>
+ * 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
+ * <firstterm>gravity hint</firstterm>.  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 #PangoAttribute<!---->s for gravity
+ * and gravity hint using pango_attr_gravity_new() and
+ * pango_attr_gravity_hint_new().
+ */
 #include "config.h"
 
 #include "pango-gravity.h"
@@ -278,7 +336,7 @@ pango_gravity_get_for_script (PangoScript      script,
  * This function is similar to pango_gravity_get_for_script() except
  * that this function makes a distinction between narrow/half-width and
  * wide/full-width characters also.  Wide/full-width characters always
- * stand <emph>upright</emph>, that is, they always take the base gravity,
+ * stand <emphasis>upright</emphasis>, that is, they always take the base gravity,
  * whereas narrow/full-width characters are always rotated in vertical
  * context.
  *