slight correction to pango_layout_get_extents(), docs still need to be

2002-01-14  Havoc Pennington  <hp@pobox.com>

	* pango/pango-layout.c: slight correction to
	pango_layout_get_extents(), docs still need to be clearer, but
	at least they aren't a cut-and-paste of glyph string docs now.

	* docs/tmpl/glyphs.sgml: add note about special-case use of
	PANGO_SCALE with font sizes

	* pango/fonts.c: fix docs to be correct about PANGO_SCALE

10 files changed, 101 insertions, 20 deletions

diff --git a/ChangeLog b/ChangeLog
index b5faa6ad..ddc994b9 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,14 @@
+2002-01-14  Havoc Pennington  <hp@pobox.com>
+
+	* pango/pango-layout.c: slight correction to
+	pango_layout_get_extents(), docs still need to be clearer, but 
+	at least they aren't a cut-and-paste of glyph string docs now. 
+	
+	* docs/tmpl/glyphs.sgml: add note about special-case use of
+	PANGO_SCALE with font sizes
+
+	* pango/fonts.c: fix docs to be correct about PANGO_SCALE
+
 2002-01-13  Havoc Pennington  <hp@pobox.com>
 
 	* pango/fonts.c: fix up docs to be clearer about PANGO_SCALE, 
diff --git a/ChangeLog.pre-1-0 b/ChangeLog.pre-1-0
index b5faa6ad..ddc994b9 100644
--- a/ChangeLog.pre-1-0
+++ b/ChangeLog.pre-1-0
@@ -1,3 +1,14 @@
+2002-01-14  Havoc Pennington  <hp@pobox.com>
+
+	* pango/pango-layout.c: slight correction to
+	pango_layout_get_extents(), docs still need to be clearer, but 
+	at least they aren't a cut-and-paste of glyph string docs now. 
+	
+	* docs/tmpl/glyphs.sgml: add note about special-case use of
+	PANGO_SCALE with font sizes
+
+	* pango/fonts.c: fix docs to be correct about PANGO_SCALE
+
 2002-01-13  Havoc Pennington  <hp@pobox.com>
 
 	* pango/fonts.c: fix up docs to be clearer about PANGO_SCALE, 
diff --git a/ChangeLog.pre-1-10 b/ChangeLog.pre-1-10
index b5faa6ad..ddc994b9 100644
--- a/ChangeLog.pre-1-10
+++ b/ChangeLog.pre-1-10
@@ -1,3 +1,14 @@
+2002-01-14  Havoc Pennington  <hp@pobox.com>
+
+	* pango/pango-layout.c: slight correction to
+	pango_layout_get_extents(), docs still need to be clearer, but 
+	at least they aren't a cut-and-paste of glyph string docs now. 
+	
+	* docs/tmpl/glyphs.sgml: add note about special-case use of
+	PANGO_SCALE with font sizes
+
+	* pango/fonts.c: fix docs to be correct about PANGO_SCALE
+
 2002-01-13  Havoc Pennington  <hp@pobox.com>
 
 	* pango/fonts.c: fix up docs to be clearer about PANGO_SCALE, 
diff --git a/ChangeLog.pre-1-2 b/ChangeLog.pre-1-2
index b5faa6ad..ddc994b9 100644
--- a/ChangeLog.pre-1-2
+++ b/ChangeLog.pre-1-2
@@ -1,3 +1,14 @@
+2002-01-14  Havoc Pennington  <hp@pobox.com>
+
+	* pango/pango-layout.c: slight correction to
+	pango_layout_get_extents(), docs still need to be clearer, but 
+	at least they aren't a cut-and-paste of glyph string docs now. 
+	
+	* docs/tmpl/glyphs.sgml: add note about special-case use of
+	PANGO_SCALE with font sizes
+
+	* pango/fonts.c: fix docs to be correct about PANGO_SCALE
+
 2002-01-13  Havoc Pennington  <hp@pobox.com>
 
 	* pango/fonts.c: fix up docs to be clearer about PANGO_SCALE, 
diff --git a/ChangeLog.pre-1-4 b/ChangeLog.pre-1-4
index b5faa6ad..ddc994b9 100644
--- a/ChangeLog.pre-1-4
+++ b/ChangeLog.pre-1-4
@@ -1,3 +1,14 @@
+2002-01-14  Havoc Pennington  <hp@pobox.com>
+
+	* pango/pango-layout.c: slight correction to
+	pango_layout_get_extents(), docs still need to be clearer, but 
+	at least they aren't a cut-and-paste of glyph string docs now. 
+	
+	* docs/tmpl/glyphs.sgml: add note about special-case use of
+	PANGO_SCALE with font sizes
+
+	* pango/fonts.c: fix docs to be correct about PANGO_SCALE
+
 2002-01-13  Havoc Pennington  <hp@pobox.com>
 
 	* pango/fonts.c: fix up docs to be clearer about PANGO_SCALE, 
diff --git a/ChangeLog.pre-1-6 b/ChangeLog.pre-1-6
index b5faa6ad..ddc994b9 100644
--- a/ChangeLog.pre-1-6
+++ b/ChangeLog.pre-1-6
@@ -1,3 +1,14 @@
+2002-01-14  Havoc Pennington  <hp@pobox.com>
+
+	* pango/pango-layout.c: slight correction to
+	pango_layout_get_extents(), docs still need to be clearer, but 
+	at least they aren't a cut-and-paste of glyph string docs now. 
+	
+	* docs/tmpl/glyphs.sgml: add note about special-case use of
+	PANGO_SCALE with font sizes
+
+	* pango/fonts.c: fix docs to be correct about PANGO_SCALE
+
 2002-01-13  Havoc Pennington  <hp@pobox.com>
 
 	* pango/fonts.c: fix up docs to be clearer about PANGO_SCALE, 
diff --git a/ChangeLog.pre-1-8 b/ChangeLog.pre-1-8
index b5faa6ad..ddc994b9 100644
--- a/ChangeLog.pre-1-8
+++ b/ChangeLog.pre-1-8
@@ -1,3 +1,14 @@
+2002-01-14  Havoc Pennington  <hp@pobox.com>
+
+	* pango/pango-layout.c: slight correction to
+	pango_layout_get_extents(), docs still need to be clearer, but 
+	at least they aren't a cut-and-paste of glyph string docs now. 
+	
+	* docs/tmpl/glyphs.sgml: add note about special-case use of
+	PANGO_SCALE with font sizes
+
+	* pango/fonts.c: fix docs to be correct about PANGO_SCALE
+
 2002-01-13  Havoc Pennington  <hp@pobox.com>
 
 	* pango/fonts.c: fix up docs to be clearer about PANGO_SCALE, 
diff --git a/docs/tmpl/glyphs.sgml b/docs/tmpl/glyphs.sgml
index 85adcfa6..04d2ba5f 100644
--- a/docs/tmpl/glyphs.sgml
+++ b/docs/tmpl/glyphs.sgml
@@ -25,6 +25,10 @@ units is dependent on the output device; it will typically be pixels
 for a screen, and points for a printer.) PANGO_SCALE is currently
 1000, but this may be changed in the future.
 </para>
+<para>
+When setting font sizes, device units are always considered to be
+points (as in "12 point font"), rather than pixels. 
+</para>
 
 
 
diff --git a/pango/fonts.c b/pango/fonts.c
index 53cbb879..a3f8cee5 100644
--- a/pango/fonts.c
+++ b/pango/fonts.c
@@ -331,7 +331,7 @@ pango_font_description_get_stretch (const PangoFontDescription *desc)
  * pango_font_description_set_size:
  * @desc: a #PangoFontDescription
  * @size: the size for the font description in pango units.
- *        There are #PANGO_SCALE Pango units in one device unit (pixel/point).
+ *        There are #PANGO_SCALE Pango units in one device unit (device unit is a point, for font sizes).
  * 
  * Sets the size field of a font description.
  **/
@@ -354,7 +354,7 @@ pango_font_description_set_size (PangoFontDescription *desc,
  * 
  * Return value: the size field for the font description in pango
  *   units.  (There are #PANGO_SCALE pango units in one device unit &mdash;
- *   pixels or points.) Returns 0 if the stretch field has not
+ *   for fonts, font points are the device unit.) Returns 0 if the stretch field has not
  *   previously been set.  pango_font_description_get_set_fields() to
  *   find out if the field was explicitely set or not.
  **/
@@ -1196,7 +1196,7 @@ pango_font_metrics_unref (PangoFontMetrics *metrics)
  * actual drawn ink. It is necessary to lay out the text to figure
  * where the ink will be.)
  * 
- * Return value: the ascent, in pango units. (1 point/pixel == #PANGO_SCALE pango units.)
+ * Return value: the ascent, in pango units. (1 point == #PANGO_SCALE pango units.)
  **/
 int
 pango_font_metrics_get_ascent (PangoFontMetrics *metrics)
@@ -1216,7 +1216,7 @@ pango_font_metrics_get_ascent (PangoFontMetrics *metrics)
  * actual drawn ink. It is necessary to lay out the text to figure
  * where the ink will be.)
  * 
- * Return value: the descent, in pango units. (1 point/pixel == #PANGO_SCALE pango units.)
+ * Return value: the descent, in pango units. (1 point == #PANGO_SCALE pango units.)
  **/
 int
 pango_font_metrics_get_descent (PangoFontMetrics *metrics)
@@ -1235,7 +1235,7 @@ pango_font_metrics_get_descent (PangoFontMetrics *metrics)
  * determining the initial size for a window. Actual characters in
  * text will be wider and narrower than this.
  * 
- * Return value: the character width, in pango units. (1 point/pixel == #PANGO_SCALE pango units.)
+ * Return value: the character width, in pango units. (1 point == #PANGO_SCALE pango units.)
  **/
 int
 pango_font_metrics_get_approximate_char_width (PangoFontMetrics *metrics)
@@ -1256,7 +1256,7 @@ pango_font_metrics_get_approximate_char_width (PangoFontMetrics *metrics)
  * is generally somewhat more accurate than the result of
  * pango_font_metrics_get_approximate_digit_width().
  * 
- * Return value: the digit width, in pango units. (1 point/pixel == #PANGO_SCALE pango units.)
+ * Return value: the digit width, in pango units. (1 point == #PANGO_SCALE pango units.)
  **/
 int
 pango_font_metrics_get_approximate_digit_width (PangoFontMetrics *metrics)
diff --git a/pango/pango-layout.c b/pango/pango-layout.c
index f26c8080..80d3f06c 100644
--- a/pango/pango-layout.c
+++ b/pango/pango-layout.c
@@ -1980,14 +1980,15 @@ pango_layout_get_extents_internal (PangoLayout    *layout,
 /**
  * pango_layout_get_extents:
  * @layout:   a #PangoLayout
- * @ink_rect: rectangle used to store the extents of the glyph string as drawn
+ * @ink_rect: rectangle used to store the extents of the layout as drawn
  *            or %NULL to indicate that the result is not needed.
- * @logical_rect: rectangle used to store the logical extents of the glyph 
- *            string or %NULL to indicate that the result is not needed.
+ * @logical_rect: rectangle used to store the logical extents of the layout 
+                 or %NULL to indicate that the result is not needed.
  * 
- * Compute the logical and ink extents of @layout. See the documentation
- * for pango_font_get_glyph_extents() for details about the interpretation
- * of the rectangles.
+ * Compute the logical and ink extents of @layout. Logical extents
+ * are usually what you want for positioning things. The extents
+ * are given in layout coordinates; layout coordinates begin at the
+ * top left corner of the layout. 
  */
 void
 pango_layout_get_extents (PangoLayout    *layout,
@@ -2002,16 +2003,15 @@ pango_layout_get_extents (PangoLayout    *layout,
 /**
  * pango_layout_get_pixel_extents:
  * @layout:   a #PangoLayout
- * @ink_rect: rectangle used to store the extents of the glyph string as drawn
+ * @ink_rect: rectangle used to store the extents of the layout as drawn
  *            or %NULL to indicate that the result is not needed.
- * @logical_rect: rectangle used to store the logical extents of the glyph 
- *            string or %NULL to indicate that the result is not needed.
+ * @logical_rect: rectangle used to store the logical extents of the 
+ *              layout or %NULL to indicate that the result is not needed.
  * 
- * Compute the logical and ink extents of @layout. See the documentation
- * for pango_font_get_glyph_extents() for details about the interpretation
- * of the rectangles. The returned rectangles are in device units, as
- * opposed to pango_layout_get_extents(), which returns the extents in
- * units of device unit / PANGO_SCALE.
+ * Compute the logical and ink extents of @layout in device units.
+ * See pango_layout_get_extents(); this function just calls
+ * pango_layout_get_extents() and then converts the extents to
+ * pixels using the #PANGO_SCALE factor.
  **/
 void
 pango_layout_get_pixel_extents (PangoLayout *layout,