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

4 files changed, 56 insertions, 12 deletions

diff --git a/ChangeLog b/ChangeLog
index 688c23f5..8a4984cf 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2007-10-30  Behdad Esfahbod  <behdad@gnome.org>
+
+	* docs/pango-sections.txt:
+	* docs/tmpl/main.sgml:
+	* docs/tmpl/vertical.sgml:
+	Improve vertical docs.
+
 2007-10-29  Behdad Esfahbod  <behdad@gnome.org>
 
 	* === Released 1.19.0 ===
diff --git a/docs/pango-sections.txt b/docs/pango-sections.txt
index 5d2da569..7571eea1 100644
--- a/docs/pango-sections.txt
+++ b/docs/pango-sections.txt
@@ -41,7 +41,6 @@ pango_context_list_families
 pango_get_mirror_char
 pango_unichar_direction
 pango_find_base_dir
-pango_gravity_to_rotation
 <SUBSECTION Standard>
 PANGO_TYPE_CONTEXT
 PangoContextClass
@@ -1066,6 +1065,7 @@ PANGO_TYPE_GRAVITY_HINT
 PANGO_GRAVITY_IS_VERTICAL
 pango_gravity_get_for_matrix
 pango_gravity_get_for_script
+pango_gravity_to_rotation
 <SUBSECTION Private>
 pango_gravity_get_type
 pango_gravity_hint_get_type
diff --git a/docs/tmpl/main.sgml b/docs/tmpl/main.sgml
index 4d2de7f0..9ab7f578 100644
--- a/docs/tmpl/main.sgml
+++ b/docs/tmpl/main.sgml
@@ -373,15 +373,6 @@ The #GObject type for #PangoDirection.
 @Returns: 
 
 
-<!-- ##### FUNCTION pango_gravity_to_rotation ##### -->
-<para>
-
-</para>
-
-@gravity: 
-@Returns: 
-
-
 <!-- ##### FUNCTION pango_break ##### -->
 <para>
 
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: 
+
+