1 files changed, 120 insertions, 2 deletions
diff --git a/docs/tmpl/glyphs.sgml b/docs/tmpl/glyphs.sgml
index fb9bd7bf..cb82ba96 100644
--- a/docs/tmpl/glyphs.sgml
+++ b/docs/tmpl/glyphs.sgml
@@ -412,6 +412,59 @@ each of which contains a list of #PangoGlyphItem.
 @glyphs: the glyphs obtained by shaping the text
          corresponding to @item.
 
+<!-- ##### STRUCT PangoGlyphItemIter ##### -->
+<para>
+A #PangoGlyphItemIter is an iterator over the clusters in a
+#PangoGlyphItem.  The <firstterm>forward direction</firstterm> of the
+iterator is the logical direction of text.  That is, with increasing
+@start_index and @start_char values.  If @glyph_item is right-to-left
+(that is, if <literal>@glyph_item->item->analysis.level</literal> is odd),
+then @start_glyph decreases as the iterator moves forward.  Moreover,
+in right-to-left cases, @start_glyph is greater than @end_glyph.
+
+An iterator should be initialized using either of
+pango_glyph_item_iter_init_start() and
+pango_glyph_item_iter_init_end(), for forward and backward iteration
+respectively, and walked over using any desired mixture of
+pango_glyph_item_iter_next_cluster() and
+pango_glyph_item_iter_prev_cluster().  A common idiom for doing a
+forward iteration over the clusters is:
+<programlisting>
+PangoGlyphItemIter cluster_iter;
+gboolean have_cluster;
+
+for (have_cluster = pango_glyph_item_iter_init_start (&amp;cluster_iter,
+                                                      glyph_item, text);
+     have_cluster;
+     have_cluster = pango_glyph_item_iter_next_cluster (&amp;cluster_iter))
+{
+  ...
+}
+</programlisting>
+
+Note that @text is the start of the text for layout, which is then
+indexed by <literal>@glyph_item->item->offset</literal> to get to the
+text of @glyph_item.  The @start_index and @end_index values can directly
+index into @text.  The @start_glyph, @end_glyph, @start_char, and @end_char
+values however are zero-based for the @glyph_item.  For each cluster, the
+item pointed at by the start variables is included in the cluster while
+the one pointed at by end variables is not.
+
+None of the members of a #PangoGlyphItemIter should be modified manually.
+
+</para>
+
+@glyph_item: the #PangoGlyphItem this iterator iterates over
+@text: the UTF-8 text that @glyph_item refers to
+@start_glyph: starting glyph of the cluster
+@start_index: starting text index of the cluster
+@start_char: starting number of characters of the cluster
+@end_glyph: ending glyph of the cluster
+@end_index: ending text index of the cluster
+@end_char: ending number of characters of the cluster
+
+@Since: 1.22
+
 <!-- ##### MACRO PANGO_TYPE_GLYPH_STRING ##### -->
 <para>
 The #GObject type for #PangoGlyphString.
@@ -534,6 +587,23 @@ The #GObject type for #PangoGlyphItem.
 @Since: 1.20
 
 
+<!-- ##### FUNCTION pango_glyph_item_copy ##### -->
+<para>
+
+</para>
+
+@orig:
+@Returns:
+
+
+<!-- ##### FUNCTION pango_glyph_item_free ##### -->
+<para>
+
+</para>
+
+@glyph_item:
+
+
 <!-- ##### FUNCTION pango_glyph_item_split ##### -->
 <para>
 
@@ -567,7 +637,15 @@ The #GObject type for #PangoGlyphItem.
 @letter_spacing: 
 
 
-<!-- ##### FUNCTION pango_glyph_item_copy ##### -->
+<!-- ##### MACRO PANGO_TYPE_GLYPH_ITEM_ITER ##### -->
+<para>
+The #GObject type for #PangoGlyphItemIter.
+</para>
+
+@Since: 1.22
+
+
+<!-- ##### FUNCTION pango_glyph_item_iter_copy ##### -->
 <para>
 
 </para>
@@ -576,11 +654,51 @@ The #GObject type for #PangoGlyphItem.
 @Returns: 
 
 
-<!-- ##### FUNCTION pango_glyph_item_free ##### -->
+<!-- ##### FUNCTION pango_glyph_item_iter_free ##### -->
+<para>
+
+</para>
+
+@iter:
+
+
+<!-- ##### FUNCTION pango_glyph_item_iter_init_start ##### -->
+<para>
+
+</para>
+
+@iter:
+@glyph_item:
+@text:
+@Returns:
+
+
+<!-- ##### FUNCTION pango_glyph_item_iter_init_end ##### -->
 <para>
 
 </para>
 
+@iter:
 @glyph_item: 
+@text:
+@Returns:
+
+
+<!-- ##### FUNCTION pango_glyph_item_iter_next_cluster ##### -->
+<para>
+
+</para>
+
+@iter:
+@Returns:
+
+
+<!-- ##### FUNCTION pango_glyph_item_iter_prev_cluster ##### -->
+<para>
+
+</para>
+
+@iter:
+@Returns: