Improve vertical docs.

2007-10-30  Behdad Esfahbod  <behdad@gnome.org>

        * docs/pango-sections.txt:
        * docs/tmpl/main.sgml:
        * docs/tmpl/vertical.sgml:
        Improve vertical docs.


svn path=/trunk/; revision=2488

1 files changed, 48 insertions, 2 deletions

diff --git a/docs/tmpl/vertical.sgml b/docs/tmpl/vertical.sgml
index 5df8f4df..917641da 100644
--- a/docs/tmpl/vertical.sgml
+++ b/docs/tmpl/vertical.sgml
@@ -24,13 +24,50 @@ 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
+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.
 </para>
+<para>
+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().
+</para>
+<para>
+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.
+</para>
+<para>
+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.
+</para>
+<para>
+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().
+</para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+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()
 </para>
 
 <!-- ##### SECTION Stability_Level ##### -->
@@ -98,3 +135,12 @@ The #GObject type for #PangoGravity.
 @Returns: 
 
 
+<!-- ##### FUNCTION pango_gravity_to_rotation ##### -->
+<para>
+
+</para>
+
+@gravity: 
+@Returns: 
+
+