Amend the shaping api docsshape-docs

Discuss problems with extra_attr indices in the
docs for pango_shape() and friends.

See: #511

1 files changed, 19 insertions, 4 deletions

diff --git a/pango/shape.c b/pango/shape.c
index efdb3177..04624b00 100644
--- a/pango/shape.c
+++ b/pango/shape.c
@@ -45,14 +45,18 @@
  * @analysis:  #PangoAnalysis structure from pango_itemize()
  * @glyphs:    glyph string in which to store results
  *
- * Given a segment of text and the corresponding
- * #PangoAnalysis structure returned from pango_itemize(),
- * convert the characters into glyphs. You may also pass
- * in only a substring of the item from pango_itemize().
+ * Given a segment of text and the corresponding #PangoAnalysis structure
+ * returned from pango_itemize(), convert the characters into glyphs. You
+ * may also pass in only a substring of the item from pango_itemize().
  *
  * It is recommended that you use pango_shape_full() instead, since
  * that API allows for shaping interaction happening across text item
  * boundaries.
+ *
+ * Note that the extra attributes in the @analyis that is returned from
+ * pango_itemize() have indices that are relative to the entire paragraph,
+ * so you need to subtract the item offset from their indices before
+ * calling pango_shape().
  */
 void
 pango_shape (const gchar         *text,
@@ -83,6 +87,11 @@ pango_shape (const gchar         *text,
  * text of which @item_text is part of, provide the broader text as
  * @paragraph_text.  If @paragraph_text is %NULL, item text is used instead.
  *
+ * Note that the extra attributes in the @analyis that is returned from
+ * pango_itemize() have indices that are relative to the entire paragraph,
+ * so you do not pass the full paragraph text as @paragraph_text, you need
+ * to subtract the item offset from their indices before calling pango_shape_full().
+ *
  * Since: 1.32
  */
 void
@@ -170,6 +179,12 @@ fallback_shape (const char          *text,
  * This is similar to pango_shape_full(), except it also takes
  * flags that can influence the shaping process.
  *
+ * Note that the extra attributes in the @analyis that is returned from
+ * pango_itemize() have indices that are relative to the entire paragraph,
+ * so you do not pass the full paragraph text as @paragraph_text, you need
+ * to subtract the item offset from their indices before calling
+ * pango_shape_with_flags().
+ *
  * Since: 1.44
  */
 void