Some unit fixups (#96335)

Fri Dec 20 11:59:22 2002  Owen Taylor  <otaylor@redhat.com>

        Some unit fixups (#96335)

        * pango/pango-layout.c pango/pango-mapping.c:
        Fix occurrences of "in thousandths of a device
        unit" to say "in #PangoGlyphUnit" which will
        give a link to the PangoGlyphUnit docs.

        * docs/tmpl/text-attributes.sgml: Change 1000 to PANGO_SCALE.

        * docs/tmpl/glyphs.sgml: Fix docs for PangoGlyphUnit,
        fix mention of value of PANGO_SCALE from 1000 to 1024.

        * pango/pango-layout.c (pango_layout_line_get_x_ranges):
        Fix the docs for @ranges so it doesn't sound like the
        coordinates are in pixels.

12 files changed, 160 insertions, 17 deletions

diff --git a/ChangeLog b/ChangeLog
index c8e3bb49..4136daa0 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,25 @@
+Fri Dec 20 11:59:22 2002  Owen Taylor  <otaylor@redhat.com>
+
+	Some unit fixups (#96335)
+
+	* pango/pango-layout.c pango/pango-mapping.c:
+	Fix occurrences of "in thousandths of a device
+	unit" to say "in #PangoGlyphUnit" which will
+	give a link to the PangoGlyphUnit docs.
+
+	* docs/tmpl/text-attributes.sgml: Change 1000 to PANGO_SCALE.
+
+	* docs/tmpl/glyphs.sgml: Fix docs for PangoGlyphUnit,
+	fix mention of value of PANGO_SCALE from 1000 to 1024.
+
+	* pango/pango-layout.c (pango_layout_line_get_x_ranges): 
+	Fix the docs for @ranges so it doesn't sound like the
+	coordinates are in pixels.
+
+Fri Dec 20 11:49:33 2002  Owen Taylor  <otaylor@redhat.com>
+
+	* README: Add a note about fonts.conf.
+
 Mon Dec 16 21:16:31 2002  Owen Taylor  <otaylor@redhat.com>
 
 	* === Released 1.1.6 ===
diff --git a/ChangeLog.pre-1-10 b/ChangeLog.pre-1-10
index c8e3bb49..4136daa0 100644
--- a/ChangeLog.pre-1-10
+++ b/ChangeLog.pre-1-10
@@ -1,3 +1,25 @@
+Fri Dec 20 11:59:22 2002  Owen Taylor  <otaylor@redhat.com>
+
+	Some unit fixups (#96335)
+
+	* pango/pango-layout.c pango/pango-mapping.c:
+	Fix occurrences of "in thousandths of a device
+	unit" to say "in #PangoGlyphUnit" which will
+	give a link to the PangoGlyphUnit docs.
+
+	* docs/tmpl/text-attributes.sgml: Change 1000 to PANGO_SCALE.
+
+	* docs/tmpl/glyphs.sgml: Fix docs for PangoGlyphUnit,
+	fix mention of value of PANGO_SCALE from 1000 to 1024.
+
+	* pango/pango-layout.c (pango_layout_line_get_x_ranges): 
+	Fix the docs for @ranges so it doesn't sound like the
+	coordinates are in pixels.
+
+Fri Dec 20 11:49:33 2002  Owen Taylor  <otaylor@redhat.com>
+
+	* README: Add a note about fonts.conf.
+
 Mon Dec 16 21:16:31 2002  Owen Taylor  <otaylor@redhat.com>
 
 	* === Released 1.1.6 ===
diff --git a/ChangeLog.pre-1-2 b/ChangeLog.pre-1-2
index c8e3bb49..4136daa0 100644
--- a/ChangeLog.pre-1-2
+++ b/ChangeLog.pre-1-2
@@ -1,3 +1,25 @@
+Fri Dec 20 11:59:22 2002  Owen Taylor  <otaylor@redhat.com>
+
+	Some unit fixups (#96335)
+
+	* pango/pango-layout.c pango/pango-mapping.c:
+	Fix occurrences of "in thousandths of a device
+	unit" to say "in #PangoGlyphUnit" which will
+	give a link to the PangoGlyphUnit docs.
+
+	* docs/tmpl/text-attributes.sgml: Change 1000 to PANGO_SCALE.
+
+	* docs/tmpl/glyphs.sgml: Fix docs for PangoGlyphUnit,
+	fix mention of value of PANGO_SCALE from 1000 to 1024.
+
+	* pango/pango-layout.c (pango_layout_line_get_x_ranges): 
+	Fix the docs for @ranges so it doesn't sound like the
+	coordinates are in pixels.
+
+Fri Dec 20 11:49:33 2002  Owen Taylor  <otaylor@redhat.com>
+
+	* README: Add a note about fonts.conf.
+
 Mon Dec 16 21:16:31 2002  Owen Taylor  <otaylor@redhat.com>
 
 	* === Released 1.1.6 ===
diff --git a/ChangeLog.pre-1-4 b/ChangeLog.pre-1-4
index c8e3bb49..4136daa0 100644
--- a/ChangeLog.pre-1-4
+++ b/ChangeLog.pre-1-4
@@ -1,3 +1,25 @@
+Fri Dec 20 11:59:22 2002  Owen Taylor  <otaylor@redhat.com>
+
+	Some unit fixups (#96335)
+
+	* pango/pango-layout.c pango/pango-mapping.c:
+	Fix occurrences of "in thousandths of a device
+	unit" to say "in #PangoGlyphUnit" which will
+	give a link to the PangoGlyphUnit docs.
+
+	* docs/tmpl/text-attributes.sgml: Change 1000 to PANGO_SCALE.
+
+	* docs/tmpl/glyphs.sgml: Fix docs for PangoGlyphUnit,
+	fix mention of value of PANGO_SCALE from 1000 to 1024.
+
+	* pango/pango-layout.c (pango_layout_line_get_x_ranges): 
+	Fix the docs for @ranges so it doesn't sound like the
+	coordinates are in pixels.
+
+Fri Dec 20 11:49:33 2002  Owen Taylor  <otaylor@redhat.com>
+
+	* README: Add a note about fonts.conf.
+
 Mon Dec 16 21:16:31 2002  Owen Taylor  <otaylor@redhat.com>
 
 	* === Released 1.1.6 ===
diff --git a/ChangeLog.pre-1-6 b/ChangeLog.pre-1-6
index c8e3bb49..4136daa0 100644
--- a/ChangeLog.pre-1-6
+++ b/ChangeLog.pre-1-6
@@ -1,3 +1,25 @@
+Fri Dec 20 11:59:22 2002  Owen Taylor  <otaylor@redhat.com>
+
+	Some unit fixups (#96335)
+
+	* pango/pango-layout.c pango/pango-mapping.c:
+	Fix occurrences of "in thousandths of a device
+	unit" to say "in #PangoGlyphUnit" which will
+	give a link to the PangoGlyphUnit docs.
+
+	* docs/tmpl/text-attributes.sgml: Change 1000 to PANGO_SCALE.
+
+	* docs/tmpl/glyphs.sgml: Fix docs for PangoGlyphUnit,
+	fix mention of value of PANGO_SCALE from 1000 to 1024.
+
+	* pango/pango-layout.c (pango_layout_line_get_x_ranges): 
+	Fix the docs for @ranges so it doesn't sound like the
+	coordinates are in pixels.
+
+Fri Dec 20 11:49:33 2002  Owen Taylor  <otaylor@redhat.com>
+
+	* README: Add a note about fonts.conf.
+
 Mon Dec 16 21:16:31 2002  Owen Taylor  <otaylor@redhat.com>
 
 	* === Released 1.1.6 ===
diff --git a/ChangeLog.pre-1-8 b/ChangeLog.pre-1-8
index c8e3bb49..4136daa0 100644
--- a/ChangeLog.pre-1-8
+++ b/ChangeLog.pre-1-8
@@ -1,3 +1,25 @@
+Fri Dec 20 11:59:22 2002  Owen Taylor  <otaylor@redhat.com>
+
+	Some unit fixups (#96335)
+
+	* pango/pango-layout.c pango/pango-mapping.c:
+	Fix occurrences of "in thousandths of a device
+	unit" to say "in #PangoGlyphUnit" which will
+	give a link to the PangoGlyphUnit docs.
+
+	* docs/tmpl/text-attributes.sgml: Change 1000 to PANGO_SCALE.
+
+	* docs/tmpl/glyphs.sgml: Fix docs for PangoGlyphUnit,
+	fix mention of value of PANGO_SCALE from 1000 to 1024.
+
+	* pango/pango-layout.c (pango_layout_line_get_x_ranges): 
+	Fix the docs for @ranges so it doesn't sound like the
+	coordinates are in pixels.
+
+Fri Dec 20 11:49:33 2002  Owen Taylor  <otaylor@redhat.com>
+
+	* README: Add a note about fonts.conf.
+
 Mon Dec 16 21:16:31 2002  Owen Taylor  <otaylor@redhat.com>
 
 	* === Released 1.1.6 ===
diff --git a/NEWS b/NEWS
index 919daa77..c5824cdd 100644
--- a/NEWS
+++ b/NEWS
@@ -112,7 +112,7 @@ Changes between 1.0.1 and 1.0.2
 * Support building with FreeType 2.1.0
 * List Sans,Serif,Monospace when listing fonts for the
   Xft and FT2 backends. (Xavier Cho)
-* Portability fixes. (David L. Cooper III, Jacob Berkman)
+* Portability fixes. (David L. Cooper II, Jacob Berkman)
 * Fix problem with pango-querymodules using g_print().
 
 Changes between 1.0.0 and 1.0.1
@@ -126,7 +126,7 @@ Changes between 1.0.0 and 1.0.1
 * Fixes for Korean glyphs in the basic-x shaper [Changwoo Ryu]
 * Improvements for computation of average char/digit width [Sven Neumann]
 * Bug and error reporting fixes 
-  [Arnaud Charlet, Erewan Chenede, Mikael Hallendal, Stefan Israelsson, 
+  [Arnaud Charlet, Erwann Chenede, Mikael Hallendal, Stefan Israelsson, 
    Alex Larsson, Soeren Sandmann, Dan Winship]
 
 ============================================================
diff --git a/README b/README
index 2bcc1c09..54e55ff6 100644
--- a/README
+++ b/README
@@ -47,6 +47,11 @@ the fontconfig library, available along with Xft in the
 also require at least version 2.0.1 of the FreeType
 library. (http://www.freetype.org)
 
+After installing fontconfig, it may be necessary to edit
+the fonts.conf file, found at $(sysconfdir)/fonts/fonts.conf
+(usually /etc/fonts/fonts.conf) to point at the fonts
+on your system.
+
 There is also a backend that uses core X protocol fonts. This
 backend only requires the standard libraries from the X window 
 system. You should already have these installed on your system, but 
diff --git a/docs/tmpl/glyphs.sgml b/docs/tmpl/glyphs.sgml
index 4700e713..49ad1cc7 100644
--- a/docs/tmpl/glyphs.sgml
+++ b/docs/tmpl/glyphs.sgml
@@ -23,7 +23,7 @@ The PANGO_SCALE macro represents the scale between dimensions used
 for Pango distances and device units. (The definition of device
 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.
+1024, but this may be changed in the future.
 </para>
 <para>
 When setting font sizes, device units are always considered to be
@@ -168,7 +168,12 @@ information for a single glyph. Distances are in
 <!-- ##### TYPEDEF PangoGlyphUnit ##### -->
 <para>
 The #PangoGlyphUnit type is used to store dimensions within
-Pango. Dimensions are stored in 1/64ths of a point.
+Pango. Dimensions are stored in 1/PANGO_SCALE of a device unit.
+(A device unit might be a pixel for screen display, or
+a point on a printer.) PANGO_SCALE is currently 1024, and
+is unlikely to change, but you should not depend on its
+exact value. The PANGO_PIXELS() macro can be used to convert
+from glyph units into device units with correct rounding.
 </para>
 
 
diff --git a/docs/tmpl/text-attributes.sgml b/docs/tmpl/text-attributes.sgml
index 5371ebf6..c908e7fd 100644
--- a/docs/tmpl/text-attributes.sgml
+++ b/docs/tmpl/text-attributes.sgml
@@ -34,7 +34,7 @@ attribute is listed in parentheses after the description.
 @PANGO_ATTR_WEIGHT: font weight (#PangoAttrInt)
 @PANGO_ATTR_VARIANT: font variant (normal or small caps) (#PangoAttrInt)
 @PANGO_ATTR_STRETCH: font stretch (#PangoAttrInt)
-@PANGO_ATTR_SIZE: font size in 1000th's of a point (#PangoAttrInt)
+@PANGO_ATTR_SIZE: font size in points divided by PANGO_SCALE (#PangoAttrInt)
 @PANGO_ATTR_FONT_DESC: font description (#PangoAttrFontDesc)
 @PANGO_ATTR_FOREGROUND: foreground color (#PangoAttrColor)
 @PANGO_ATTR_BACKGROUND: background color (#PangoAttrColor)
diff --git a/pango/mapping.c b/pango/mapping.c
index 46e45ac8..f25dd9aa 100644
--- a/pango/mapping.c
+++ b/pango/mapping.c
@@ -159,7 +159,7 @@ pango_glyph_string_index_to_x (PangoGlyphString *glyphs,
  * @text:      the text for the run
  * @length:    the number of bytes (not characters) in text.
  * @analysis:  the analysis information return from pango_itemize()
- * @x_pos:     the x offset (in thousands of a device unit)
+ * @x_pos:     the x offset (in #PangoGlyphUnit)
  * @index_:    location to store calculated byte index within @text
  * @trailing:  location to store a integer indicating where
  *             whether the user clicked on the leading or trailing
diff --git a/pango/pango-layout.c b/pango/pango-layout.c
index d80f1f27..2df1cbbb 100644
--- a/pango/pango-layout.c
+++ b/pango/pango-layout.c
@@ -475,7 +475,7 @@ pango_layout_set_spacing (PangoLayout *layout,
  * 
  * Gets the amount of spacing between the lines of the layout.
  * 
- * Return value: the spacing (in thousandths of a device unit)
+ * Return value: the spacing (in #PangoGlyphUnit)
  **/
 int
 pango_layout_get_spacing (PangoLayout *layout)
@@ -959,7 +959,7 @@ pango_layout_get_line (PangoLayout *layout,
  * @trailing: an integer indicating the edge of the grapheme to retrieve 
  *            the position of. If 0, the trailing edge of the grapheme, 
  *            if > 0, the leading of the grapheme.
- * @x_pos: location to store the x_offset (in thousandths of a device unit)
+ * @x_pos: location to store the x_offset (in #PangoGlyphUnit)
  * 
  * Converts an index within a line to a X position.
  *
@@ -1347,9 +1347,9 @@ pango_layout_move_cursor_visually (PangoLayout *layout,
 /**
  * pango_layout_xy_to_index:
  * @layout:    a #PangoLayout
- * @x:         the X offset (in thousandths of a device unit)
+ * @x:         the X offset (in #PangoGlyphUnit)
  *             from the left edge of the layout.
- * @y:         the Y offset (in thousandths of a device unit)
+ * @y:         the Y offset (in #PangoGlyphUnit)
  *             from the top edge of the layout
  * @index_:    location to store calculated byte index
  * @trailing:  location to store a integer indicating where
@@ -2015,7 +2015,7 @@ pango_layout_get_extents (PangoLayout    *layout,
  * 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.
+ * device units using the #PANGO_SCALE factor.
  **/
 void
 pango_layout_get_pixel_extents (PangoLayout *layout,
@@ -3081,7 +3081,7 @@ pango_layout_line_unref (PangoLayoutLine *line)
 /**
  * pango_layout_line_x_to_index:
  * @line:      a #PangoLayoutLine
- * @x_pos:     the x offset (in thousands of a device unit)
+ * @x_pos:     the x offset (in #PangoGlyphUnit)
  *             from the left edge of the line.
  * @index_:    location to store calculated byte offset for
  *             the grapheme in which the user clicked.
@@ -3307,11 +3307,12 @@ pango_layout_line_x_to_index (PangoLayoutLine *line,
  *               the last range will extend all the way to the trailing
  *               edge of the layout. Otherwise, it will end at the
  *               trailing edge of the last character.
- * @ranges:      location to store a pointer to an array of arranges.
+ * @ranges:      location to store a pointer to an array of ranges.
  *               The array will be of length 2*@n_ranges, with each
- *               range including the pixels from (*ranges)[2*n] to
- *               (*ranges)[2*n + 1] - 1. This array must be freed
- *               with g_free. The pixels are in layout coordinates.
+ *               range starting at (*ranges)[2*n] and of width
+ *               (*ranges)[2*n + 1] - (*ranges)[2*n]. This array must be
+ *               freed with g_free. The coordinates are relative to the
+ *               layout and are in #PangoGlyphUnit.
  * @n_ranges: The number of ranges stored in @ranges.
  * 
  * Get a list of visual ranges corresponding to a given logical range.
@@ -3722,7 +3723,7 @@ pango_layout_line_new (PangoLayout *layout)
  * 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_line_get_extents(), which returns the extents in
- * units of device unit / PANGO_SCALE.
+ * #PangoGlyphUnit.
  **/
 void
 pango_layout_line_get_pixel_extents (PangoLayoutLine *layout_line,