Rename PangoLayoutRun to PangoGlyphItem (with a typedef for compat), add

Sun Nov 17 23:28:26 2002  Owen Taylor  <otaylor@redhat.com>

        * pango/pango-glyph-item.[ch] pango/pango-layout.h:
        Rename PangoLayoutRun to PangoGlyphItem (with a
        typedef for compat), add pango_glyph_item_split(),
        pango_glyph_item_apply_attrs().

        * pango/pango-attributes.[ch]: Add
        pango_attr_list_filter(), pango_attr_iterator_get_attrs().

        * pango/pango-layout.c: Remove attributes that don't
        affect shaping before shaping, shape and then add
        them back. Fixes the infamous "underscores break
        arabic shaping" bug (#83058)

        * pango/pango-item.h: Remove an extraneous include.

        * pango/pango-layout.c (imposed_shape): Fix bytes/chars
        problem for glyph->log_clusters.

        * pango/pango-layout.c (cluster_end_index)
        * pango/pango-layout.c (pango_layout_iter_next_cluster): Fix
        confusion between global indices and run-relative indices.

        * docs/tmpl/glyphs.sgml: Improve docs for log_clusters.

        * docs/*: Document new API and PangoOTRuleset

7 files changed, 106 insertions, 24 deletions

diff --git a/docs/pango-sections.txt b/docs/pango-sections.txt
index 8e3688ff..3ba5dbd7 100644
--- a/docs/pango-sections.txt
+++ b/docs/pango-sections.txt
@@ -65,6 +65,7 @@ PangoGlyphGeometry
 PangoGlyphUnit
 PangoGlyphVisAttr
 PangoGlyphString
+PangoGlyphItem
 PANGO_TYPE_GLYPH_STRING
 pango_glyph_string_new
 pango_glyph_string_copy
@@ -75,6 +76,8 @@ pango_glyph_string_extents_range
 pango_glyph_string_index_to_x
 pango_glyph_string_x_to_index
 pango_glyph_string_get_logical_widths
+pango_glyph_item_split
+pango_glyph_item_apply_attrs
 
 <SUBSECTION Private>
 pango_glyph_string_get_type
@@ -305,6 +308,8 @@ pango_attr_list_insert
 pango_attr_list_insert_before
 pango_attr_list_change
 pango_attr_list_splice
+pango_attr_list_filter
+PangoAttrFilterFunc
 pango_attr_list_get_iterator
 PangoAttrIterator
 pango_attr_iterator_copy
@@ -312,6 +317,7 @@ pango_attr_iterator_next
 pango_attr_iterator_range
 pango_attr_iterator_get
 pango_attr_iterator_get_font
+pango_attr_iterator_get_attrs
 pango_attr_iterator_destroy
 <SUBSECTION Private>
 pango_attr_type_get_type
diff --git a/docs/tmpl/fonts.sgml b/docs/tmpl/fonts.sgml
index 78a94741..49a96eaa 100644
--- a/docs/tmpl/fonts.sgml
+++ b/docs/tmpl/fonts.sgml
@@ -761,7 +761,12 @@ Returns the type of a #PangoFontMap.
 
 <!-- ##### STRUCT PangoFontset ##### -->
 <para>
-
+A #PangoFontset represents a set of #PangoFont to use
+when rendering text. It is the result of resolving a
+#PangoFontDescription against a particular #PangoContext.
+It has operations for finding the component font for
+a particular Unicode character, and for finding a composite
+set of metrics for the entire fontset.
 </para>
 
 
@@ -810,7 +815,10 @@ a particular #PangoFontset implementation.
 
 <!-- ##### STRUCT PangoFontsetSimple ##### -->
 <para>
-
+#PangoFontSetSimple is a implementation of the abstract
+#PangoFontSet base class in terms of an array of fonts,
+which the creator provides when constructing the
+#PangoFontSetSimple.
 </para>
 
 
diff --git a/docs/tmpl/glyphs.sgml b/docs/tmpl/glyphs.sgml
index 9be721ce..e4ec644e 100644
--- a/docs/tmpl/glyphs.sgml
+++ b/docs/tmpl/glyphs.sgml
@@ -218,24 +218,15 @@ accessible fields
 </row>
 
 <row>
-<entry>PangoGlyph *#glyphs;</entry>
-<entry>an array of glyphs of length <structfield>num_glyphs</structfield>.</entry>
-</row>
-
-<row>
-<entry>PangoGlyphGeometry *#geometry;</entry>
-<entry>an array of #PangoGlyphGeometry structures corresponding to <structfield>glyphs</structfield>.</entry>
-</row>
-
-<row>
-<entry>PangoGlyphVisAttr *#attrs;</entry>
-<entry>an array of #PangoGlyphVisAttr structures corresponding to <structfield>glyphs</structfield>.</entry>
+<entry>PangoGlyphInfo *#glyphs;</entry>
+<entry>an array of #PangoGlyphInfo structures of length <structfield>num_glyphs</structfield>.</entry>
 </row>
 
 <row>
 <entry>gint *#log_clusters;</entry>
-<entry>for each glyph, the character index (should this be byte
-       index?) of the starting character for the cluster.</entry>
+<entry>for each glyph, byte index of the starting character for the
+cluster. The indices are relative to the start of the text
+corresponding to the PangoGlyphString.</entry>
 </row>
 
 </tbody></tgroup></informaltable>
@@ -245,6 +236,20 @@ accessible fields
 @glyphs: 
 @log_clusters: 
 
+<!-- ##### STRUCT PangoGlyphItem ##### -->
+<para>
+A #PangoGlyphItem is a pair of a #PangoItem and the glyphs
+resulting from shaping the text corresponding to an item.
+As an example of the usage of #PangoGlyphItem, the results
+of shaping text with #PangoLayout is a list of #PangoLayoutLine,
+each of which contains a list of #PangoGlyphItem.
+</para>
+
+@item: a #PangoItem structure that provides information
+       about a segment of text.
+@glyphs: the glyphs obtained by shaping the text
+         corresponding to @item.
+
 <!-- ##### MACRO PANGO_TYPE_GLYPH_STRING ##### -->
 <para>
 The GObject type for #PangoGlyphString.
@@ -350,3 +355,25 @@ The GObject type for #PangoGlyphString.
 @logical_widths: 
 
 
+<!-- ##### FUNCTION pango_glyph_item_split ##### -->
+<para>
+
+</para>
+
+@orig: 
+@text: 
+@split_index: 
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_glyph_item_apply_attrs ##### -->
+<para>
+
+</para>
+
+@glyph_item: 
+@text: 
+@list: 
+@Returns: 
+
+
diff --git a/docs/tmpl/layout.sgml b/docs/tmpl/layout.sgml
index dc52d942..9202d7db 100644
--- a/docs/tmpl/layout.sgml
+++ b/docs/tmpl/layout.sgml
@@ -642,15 +642,14 @@ code specific to each rendering system.
 @length: the length of the line in bytes.
 @runs: a list containing the runs of the line in visual order.
 
-<!-- ##### STRUCT PangoLayoutRun ##### -->
+<!-- ##### TYPEDEF PangoLayoutRun ##### -->
 <para>
 The #PangoLayoutRun structure represents a single run within
-a #PangoLayoutLine.
+a #PangoLayoutLine; it is simply an alternate name for
+#PangoGlyphItem, present for backwards compatibility.
+See the #PangoGlyphItem docs for details on the fields.
 </para>
 
-@item: a #PangoItem structure that provides information
-       about the segment of text in this run.
-@glyphs: the glyphs obtained by shaping the text for this item.
 
 <!-- ##### FUNCTION pango_layout_line_ref ##### -->
 <para>
diff --git a/docs/tmpl/opentype.sgml b/docs/tmpl/opentype.sgml
index f4c853b1..306440ba 100644
--- a/docs/tmpl/opentype.sgml
+++ b/docs/tmpl/opentype.sgml
@@ -35,7 +35,14 @@ use pango_ot_info_new().
 
 <!-- ##### STRUCT PangoOTRuleset ##### -->
 <para>
-
+The <structname>PangoOTRuleSet</structname> structure holds a
+set of features selected from the tables in an OpenType font.
+(A feature is an operation such as adjusting glyph positioning
+that should be applied to a text feature such as a certain
+type of accent.) A <structname>PangoOTRuleSet</structname>
+is created with pango_ot_ruleset_new(), features are addded
+to it with pango_ot_ruleset_add_feature(), then it is
+applied to a #PangoGlyphString with pango_ot_ruleset_shape().
 </para>
 
 
diff --git a/docs/tmpl/pango-indic.sgml b/docs/tmpl/pango-indic.sgml
index f4cfd245..3c8bf16f 100644
--- a/docs/tmpl/pango-indic.sgml
+++ b/docs/tmpl/pango-indic.sgml
@@ -2,11 +2,15 @@
 Indic Engine Support
 
 <!-- ##### SECTION Short_Description ##### -->
-
+Indic support for legacy shaper engines.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+The <function>pango_indic_*</function> functiosn are used to
+implement indic shaping support for certain legacy shaping engines,
+in particular the shaping engines for bitmap X fonts.
+These are basically internal routines and should not be
+used by applications.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
diff --git a/docs/tmpl/text-attributes.sgml b/docs/tmpl/text-attributes.sgml
index d05e9f46..56e1a796 100644
--- a/docs/tmpl/text-attributes.sgml
+++ b/docs/tmpl/text-attributes.sgml
@@ -593,6 +593,28 @@ The GObject type for #PangoAttrList.
 @len: 
 
 
+<!-- ##### FUNCTION pango_attr_list_filter ##### -->
+<para>
+
+</para>
+
+@list: 
+@func: 
+@data: 
+@Returns: 
+
+
+<!-- ##### USER_FUNCTION PangoAttrFilterFunc ##### -->
+<para>
+A predicate function used by pango_attr_list_filter()
+to filter out a subset of attributes for a list.
+</para>
+
+@attribute: a #PangoAttribute
+@data: callback data passed to pango_attr_list_filter()
+@Returns: %TRUE if the attribute should be filtered out
+
+
 <!-- ##### FUNCTION pango_attr_list_get_iterator ##### -->
 <para>
 
@@ -663,6 +685,15 @@ attributes currently in effect can be queried.
 @extra_attrs: 
 
 
+<!-- ##### FUNCTION pango_attr_iterator_get_attrs ##### -->
+<para>
+
+</para>
+
+@iterator: 
+@Returns: 
+
+
 <!-- ##### FUNCTION pango_attr_iterator_destroy ##### -->
 <para>