Document how Pango's vertical text support works.

2007-05-24  Behdad Esfahbod  <behdad@gnome.org>

        * docs/tmpl/vertical.sgml: Document how Pango's vertical text support
        works.


svn path=/trunk/; revision=2318

1 files changed, 15 insertions, 0 deletions

diff --git a/docs/tmpl/vertical.sgml b/docs/tmpl/vertical.sgml
index ccbea1ea..de80afd3 100644
--- a/docs/tmpl/vertical.sgml
+++ b/docs/tmpl/vertical.sgml
@@ -9,6 +9,21 @@ Laying text out in vertical directions
 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 and rotate the layout normally.  Pango will make sure that
+Asian languages take the right form, while other scripts are rotated normally.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->