Update docs.

2006-04-29  Behdad Esfahbod  <behdad@gnome.org>

        * docs/tmpl/atsui-fonts.sgml:
        * docs/tmpl/coverage-maps.sgml:
        * docs/tmpl/engines.sgml:
        * docs/tmpl/fonts.sgml:
        * docs/tmpl/freetype-fonts.sgml:
        * docs/tmpl/glyphs.sgml:
        * docs/tmpl/layout.sgml:
        * docs/tmpl/main.sgml:
        * docs/tmpl/modules.sgml:
        * docs/tmpl/opentype.sgml:
        * docs/tmpl/pango-engine-lang.sgml:
        * docs/tmpl/pango-engine-shape.sgml:
        * docs/tmpl/pango-renderer.sgml:
        * docs/tmpl/pangocairo.sgml:
        * docs/tmpl/pangofc-decoder.sgml:
        * docs/tmpl/pangofc-font.sgml:
        * docs/tmpl/pangofc-fontmap.sgml:
        * docs/tmpl/scripts.sgml:
        * docs/tmpl/tab-stops.sgml:
        * docs/tmpl/text-attributes.sgml:
        * docs/tmpl/win32-fonts.sgml:
        * docs/tmpl/x-fonts.sgml:
        * docs/tmpl/xft-fonts.sgml:
        * examples/Makefile.am:
        * pango/modules.c:
        * pango/pango-coverage.c: Update docs.

27 files changed, 304 insertions, 167 deletions

diff --git a/ChangeLog b/ChangeLog
index a89d3376..66cbf802 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,63 @@
 2006-04-29  Behdad Esfahbod  <behdad@gnome.org>
 
+	* docs/tmpl/atsui-fonts.sgml:
+	* docs/tmpl/coverage-maps.sgml:
+	* docs/tmpl/engines.sgml:
+	* docs/tmpl/fonts.sgml:
+	* docs/tmpl/freetype-fonts.sgml:
+	* docs/tmpl/glyphs.sgml:
+	* docs/tmpl/layout.sgml:
+	* docs/tmpl/main.sgml:
+	* docs/tmpl/modules.sgml:
+	* docs/tmpl/opentype.sgml:
+	* docs/tmpl/pango-engine-lang.sgml:
+	* docs/tmpl/pango-engine-shape.sgml:
+	* docs/tmpl/pango-renderer.sgml:
+	* docs/tmpl/pangocairo.sgml:
+	* docs/tmpl/pangofc-decoder.sgml:
+	* docs/tmpl/pangofc-font.sgml:
+	* docs/tmpl/pangofc-fontmap.sgml:
+	* docs/tmpl/scripts.sgml:
+	* docs/tmpl/tab-stops.sgml:
+	* docs/tmpl/text-attributes.sgml:
+	* docs/tmpl/win32-fonts.sgml:
+	* docs/tmpl/x-fonts.sgml:
+	* docs/tmpl/xft-fonts.sgml:
+	* examples/Makefile.am:
+	* pango/modules.c:
+	* pango/pango-coverage.c: Update docs.
+
+2006-04-29  Behdad Esfahbod  <behdad@gnome.org>
+
+	* docs/tmpl/atsui-fonts.sgml:
+	* docs/tmpl/coverage-maps.sgml:
+	* docs/tmpl/engines.sgml:
+	* docs/tmpl/fonts.sgml:
+	* docs/tmpl/freetype-fonts.sgml:
+	* docs/tmpl/glyphs.sgml:
+	* docs/tmpl/layout.sgml:
+	* docs/tmpl/main.sgml:
+	* docs/tmpl/modules.sgml:
+	* docs/tmpl/opentype.sgml:
+	* docs/tmpl/pango-engine-lang.sgml:
+	* docs/tmpl/pango-engine-shape.sgml:
+	* docs/tmpl/pango-renderer.sgml:
+	* docs/tmpl/pangocairo.sgml:
+	* docs/tmpl/pangofc-decoder.sgml:
+	* docs/tmpl/pangofc-font.sgml:
+	* docs/tmpl/pangofc-fontmap.sgml:
+	* docs/tmpl/scripts.sgml:
+	* docs/tmpl/tab-stops.sgml:
+	* docs/tmpl/text-attributes.sgml:
+	* docs/tmpl/win32-fonts.sgml:
+	* docs/tmpl/x-fonts.sgml:
+	* docs/tmpl/xft-fonts.sgml:
+	* examples/Makefile.am:
+	* pango/modules.c:
+	* pango/pango-coverage.c:
+
+2006-04-29  Behdad Esfahbod  <behdad@gnome.org>
+
 	Bug 337594 – pango_glyph_string_extents_range possible bug
 
 	* pango/glyphstring.c (pango_glyph_string_extents_range): Add offset
diff --git a/docs/tmpl/atsui-fonts.sgml b/docs/tmpl/atsui-fonts.sgml
index aa6f536e..f838f998 100644
--- a/docs/tmpl/atsui-fonts.sgml
+++ b/docs/tmpl/atsui-fonts.sgml
@@ -6,7 +6,8 @@ Font handling and rendering with ATSUI fonts
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+The macros and functions in this section are used to access fonts natively on
+MacOS systems using the ATSUI text rendering subsystem.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -14,6 +15,9 @@ Font handling and rendering with ATSUI fonts
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT PangoCairoATSUIFont ##### -->
 <para>
 
diff --git a/docs/tmpl/coverage-maps.sgml b/docs/tmpl/coverage-maps.sgml
index f88fa32f..69c71626 100644
--- a/docs/tmpl/coverage-maps.sgml
+++ b/docs/tmpl/coverage-maps.sgml
@@ -17,9 +17,12 @@ to represent that information.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### ENUM PangoCoverageLevel ##### -->
 <para>
-Used to indicate how well a font can represent a particular ISO 10646
+Used to indicate how well a font can represent a particular Unicode
 character point for a particular script.
 </para>
 
@@ -43,8 +46,8 @@ The #GObject type for #PangoCoverageLevel.
 
 <!-- ##### STRUCT PangoCoverage ##### -->
 <para>
-The #PangoCoverage structure represents a map from ISO-10646 character
-point to #PangoCoverageLevel. It is an opaque structure with no public fields.
+The #PangoCoverage structure represents a map from Unicode characters
+to #PangoCoverageLevel. It is an opaque structure with no public fields.
 </para>
 
 
diff --git a/docs/tmpl/engines.sgml b/docs/tmpl/engines.sgml
index fb7fdfd2..2f8efcae 100644
--- a/docs/tmpl/engines.sgml
+++ b/docs/tmpl/engines.sgml
@@ -28,6 +28,9 @@ function is used when building a catalog of all available modules.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT PangoEngineInfo ##### -->
 <para>
 The #PangoEngineInfo structure contains information about a particular
@@ -37,8 +40,8 @@ engine. It contains the following fields:
 @id: a unique string ID for the engine.
 @engine_type: a string identifying the engine type.
 @render_type: a string identifying the render type.
-@scripts: 
-@n_scripts: 
+@scripts: array of scripts this engine supports.
+@n_scripts: number of items in @scripts.
 
 <!-- ##### STRUCT PangoEngineScriptInfo ##### -->
 <para>
diff --git a/docs/tmpl/fonts.sgml b/docs/tmpl/fonts.sgml
index 0d777992..416a1870 100644
--- a/docs/tmpl/fonts.sgml
+++ b/docs/tmpl/fonts.sgml
@@ -19,6 +19,9 @@ to load a font of a given description.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT PangoFontDescription ##### -->
 <para>
 The #PangoFontDescription structure represents the description
@@ -93,15 +96,15 @@ An enumeration specifying the width of the font relative to other designs
 within a family.
 </para>
 
-@PANGO_STRETCH_ULTRA_CONDENSED: 
-@PANGO_STRETCH_EXTRA_CONDENSED: 
-@PANGO_STRETCH_CONDENSED: 
-@PANGO_STRETCH_SEMI_CONDENSED: 
+@PANGO_STRETCH_ULTRA_CONDENSED: ultra condensed width
+@PANGO_STRETCH_EXTRA_CONDENSED: extra condensed width
+@PANGO_STRETCH_CONDENSED: condensed width
+@PANGO_STRETCH_SEMI_CONDENSED: semi condensed width
 @PANGO_STRETCH_NORMAL: the normal width
-@PANGO_STRETCH_SEMI_EXPANDED: 
-@PANGO_STRETCH_EXPANDED: 
-@PANGO_STRETCH_EXTRA_EXPANDED: 
-@PANGO_STRETCH_ULTRA_EXPANDED: 
+@PANGO_STRETCH_SEMI_EXPANDED: semi expanded width
+@PANGO_STRETCH_EXPANDED: expanded width
+@PANGO_STRETCH_EXTRA_EXPANDED: extra expanded width
+@PANGO_STRETCH_ULTRA_EXPANDED: ultra expanded width
 
 <!-- ##### MACRO PANGO_TYPE_STRETCH ##### -->
 <para>
@@ -412,15 +415,21 @@ the documentation of the corresponding getters for documentation
 of their meaning.
 </para>
 
-@ref_count: 
-@ascent: 
-@descent: 
-@approximate_char_width: 
-@approximate_digit_width: 
-@underline_position: 
-@underline_thickness: 
-@strikethrough_position: 
-@strikethrough_thickness: 
+@ref_count: reference count.  Used internally.  See pango_font_metrics_ref()
+            and pango_font_metrics_unref().
+@ascent: the distance from the baseline to the highest point of the glyphs of
+	 the font. This is positive in practically all fonts.
+@descent: the distance from the baseline to the lowest point of the glyphs of
+	 the font. This is positive in practically all fonts.
+@approximate_char_width: approximate average width of the regular glyphs of
+         the font.
+@approximate_digit_width: approximate average width of the glyphs for digits
+         of the font.
+@underline_position: position of the underline. This is normally negative.
+@underline_thickness: thickness of the underline.
+@strikethrough_position: position of the strikethrough line. This is
+	 normally positive.
+@strikethrough_thickness: thickness of the strikethrough line.
 
 <!-- ##### MACRO PANGO_TYPE_FONT_METRICS ##### -->
 <para>
@@ -782,13 +791,16 @@ The #PangoFontMapClass structure holds the virtual functions for
 a particular #PangoFontMap implementation.
 </para>
 
-@parent_class: 
+@parent_class: parent #GObjectClass.
 @load_font: a function to load a font with a given description. See
-            pango_font_map_load_font()
+            pango_font_map_load_font().
 @list_families: A function to list available font families. See
                 pango_font_map_list_families().
-@load_fontset: 
-@shape_engine_type: 
+@load_fontset: a function to load a fontset with a given given description
+             suitable for a particular language. See
+	     pango_font_map_load_fontset().
+@shape_engine_type: the type of rendering-system-dependent engines that
+             can handle fonts of this fonts loaded with this fontmap.
 
 <!-- ##### MACRO PANGO_FONT_MAP_CLASS ##### -->
 <para>
@@ -880,13 +892,14 @@ The #PangoFontsetClass structure holds the virtual functions for
 a particular #PangoFontset implementation.
 </para>
 
-@parent_class: 
+@parent_class: parent #GObjectClass.
 @get_font: a function to get the font in the fontset that contains the 
    best glyph for the given Unicode character; see pango_fontset_get_font().
 @get_metrics: a function to get overall metric information for the fonts 
    in the fontset; see pango_fontset_get_metrics().
 @get_language: a function to get the language of the fontset.
-@foreach: 
+@foreach: a function to loop over the fonts in the fontset. See
+   pango_fontset_foreach().
 
 <!-- ##### FUNCTION pango_fontset_get_font ##### -->
 <para>
diff --git a/docs/tmpl/freetype-fonts.sgml b/docs/tmpl/freetype-fonts.sgml
index e39ba6bb..cbe92eb7 100644
--- a/docs/tmpl/freetype-fonts.sgml
+++ b/docs/tmpl/freetype-fonts.sgml
@@ -6,7 +6,8 @@ Functions for shape engines to manipulate FreeType fonts
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+The macros and functions in this section are used to access fonts and render
+text to bitmaps using the FreeType 2 library.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -14,6 +15,9 @@ Functions for shape engines to manipulate FreeType fonts
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT PangoFT2FontMap ##### -->
 <para>
 The #PangoFT2FontMap is the #PangoFontMap implementation for FreeType fonts.
diff --git a/docs/tmpl/glyphs.sgml b/docs/tmpl/glyphs.sgml
index ebf5fafa..873a9f78 100644
--- a/docs/tmpl/glyphs.sgml
+++ b/docs/tmpl/glyphs.sgml
@@ -17,6 +17,9 @@ glyphs.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### MACRO PANGO_SCALE ##### -->
 <para>
 The %PANGO_SCALE macro represents the scale between dimensions used
@@ -260,27 +263,15 @@ to convert from glyph units into device units with correct rounding.
 <!-- ##### STRUCT PangoGlyphVisAttr ##### -->
 <para>
 The PangoGlyphVisAttr is used to communicate information between
-the shaping phase and the rendering phase. It's contents
-are still evolving.
-
-<informaltable pgwide="1" frame="none" role="struct">
-<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
-<tbody>
-
-<row>
-<entry>#guint is_cluster_start : 1;</entry>
-<entry>set for the first logical glyph in each cluster. (Clusters
-       are stored in visual order, within the cluster, glyphs
-       are always ordered in logical order, since visual
-       order is meaningless; that is, in Arabic text, accent glyphs
-       follow the glyphs for the base character.)
-</entry>
-</row>
-
-</tbody></tgroup></informaltable>
+the shaping phase and the rendering phase.  More attributes may be
+added in the future.
 </para>
 
-@is_cluster_start: 
+@is_cluster_start: set for the first logical glyph in each cluster. (Clusters
+		   are stored in visual order, within the cluster, glyphs
+		   are always ordered in logical order, since visual
+		   order is meaningless; that is, in Arabic text, accent glyphs
+		   follow the glyphs for the base character.)
 
 <!-- ##### STRUCT PangoGlyphString ##### -->
 <para>
diff --git a/docs/tmpl/layout.sgml b/docs/tmpl/layout.sgml
index bcb28fb0..8dd4b695 100644
--- a/docs/tmpl/layout.sgml
+++ b/docs/tmpl/layout.sgml
@@ -19,6 +19,9 @@ at once.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT PangoLayout ##### -->
 <para>
 The #PangoLayout structure represents and entire paragraph
diff --git a/docs/tmpl/main.sgml b/docs/tmpl/main.sgml
index bd8a17f3..ab47b4df 100644
--- a/docs/tmpl/main.sgml
+++ b/docs/tmpl/main.sgml
@@ -17,6 +17,9 @@ various steps of this process.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT PangoContext ##### -->
 <para>
 The #PangoContext structure stores global information
@@ -45,10 +48,10 @@ fields:
 
 @shape_engine: the engine for doing rendering-system-dependent processing.
 @lang_engine: the engine for doing rendering-system-independent processing.
-@font: 
+@font: the font for this segment.
 @level: the bidrectional level for this segment.
-@language: 
-@extra_attrs: 
+@language: the detected language for this segment.
+@extra_attrs: extra attributes for this segment.
 
 <!-- ##### ENUM PangoDirection ##### -->
 <para>
@@ -366,17 +369,31 @@ The #PangoLogAttr structure stores information
 about the attributes of a single character.
 </para>
 
-@is_line_break: 
-@is_mandatory_break: 
-@is_char_break: 
-@is_white: 
-@is_cursor_position: 
-@is_word_start: 
-@is_word_end: 
-@is_sentence_boundary: 
-@is_sentence_start: 
-@is_sentence_end: 
-@backspace_deletes_character: If set, backspace deletes one character
+@is_line_break: if set, can break line in front of character
+@is_mandatory_break: if set, must break line in front of character
+@is_char_break: if set, can break here when doing character wrapping
+@is_white: is whitespace character
+@is_cursor_position: if set, cursor can appear in front of character.
+	i.e. this is a grapheme boundary, or the first character
+        in the text.
+@is_word_start: is first character in a word
+@is_word_end: is first non-word char after a word
+	Note that in degenerate cases, you could have both @is_word_start
+	and @is_word_end set for some character.
+@is_sentence_boundary: is a sentence boundary.
+        There are two ways to divide sentences. The first assigns all
+	intersentence whitespace/control/format chars to some sentence,
+	so all chars are in some sentence; @is_sentence_boundary denotes
+	the boundaries there. The second way doesn't assign
+	between-sentence spaces, etc. to any sentence, so
+	@is_sentence_start/@is_sentence_end mark the boundaries
+	of those sentences.
+@is_sentence_start: is first character in a sentence
+@is_sentence_end: is first char after a sentence.
+	Note that in degenerate cases, you could have both @is_sentence_start
+	and @is_sentence_end set for some character. (e.g. no space after a
+	period, so the next sentence starts right away)
+@backspace_deletes_character: if set, backspace deletes one character
                               rather than the entire grapheme cluster. This
                               field is only meaningful on grapheme
                               boundaries (where @is_cursor_position is
diff --git a/docs/tmpl/modules.sgml b/docs/tmpl/modules.sgml
index e552e387..003840a0 100644
--- a/docs/tmpl/modules.sgml
+++ b/docs/tmpl/modules.sgml
@@ -6,7 +6,8 @@ Support for loadable modules
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+Functions and macros in this section are used to support loading dynamic
+modules that add engines to Pango at run time.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -14,6 +15,9 @@ Support for loadable modules
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT PangoIncludedModule ##### -->
 <para>
 The #PangoIncludedModule structure for a statically linked module 
@@ -21,10 +25,10 @@ contains the functions that would otherwise be loaded from a dynamically
 loaded module.
 </para>
 
-@list: 
-@init: 
-@exit: 
-@create: 
+@list: a function that lists the engines defined in this module.
+@init: a function to initialize the module.
+@exit: a function to finilize the module.
+@create: a function to create an engine, given the engine name.
 
 <!-- ##### STRUCT PangoMap ##### -->
 <para>
diff --git a/docs/tmpl/opentype.sgml b/docs/tmpl/opentype.sgml
index d62bb3d9..bc31542f 100644
--- a/docs/tmpl/opentype.sgml
+++ b/docs/tmpl/opentype.sgml
@@ -6,7 +6,9 @@ Obtaining information from OpenType tables
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+Functions and macros in this section are used to implement the OpenType Layout
+features and algorithms.  These are mostly useful when writing Fontconfig-based
+shaping engines
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -14,6 +16,9 @@ Obtaining information from OpenType tables
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### TYPEDEF PangoOTTag ##### -->
 <para>
 The <type>PangoOTTag</type> typedef is used to represent TrueType and OpenType
diff --git a/docs/tmpl/pango-engine-lang.sgml b/docs/tmpl/pango-engine-lang.sgml
index 79b08f21..dff0fd42 100644
--- a/docs/tmpl/pango-engine-lang.sgml
+++ b/docs/tmpl/pango-engine-lang.sgml
@@ -6,7 +6,9 @@ Rendering-system independent script engines
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+The <firstterm>language engines</firstterm> are rendering-system independent
+engines that determine line, word, and character breaks for character strings.
+These engines are used in pango_break().
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -14,6 +16,9 @@ Rendering-system independent script engines
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT PangoEngineLang ##### -->
 <para>
 </para>
@@ -29,7 +34,7 @@ Rendering-system independent script engines
 <!-- ##### MACRO PANGO_ENGINE_TYPE_LANG ##### -->
 <para>
 A string constant defining the engine type
-for <firstterm>language engines</firstterm>.
+for language engines.
 These engines derive from #PangoEngineLang.
 </para>
 
@@ -42,14 +47,6 @@ These engines derive from #PangoEngineLang.
 
 @name: 
 @prefix: 
-@\
-				       class_init:
-@\
-				       class_init:
-@\
-				       class_init:
-@\
-				       class_init:
 @class_init: 
 @instance_init: 
 
diff --git a/docs/tmpl/pango-engine-shape.sgml b/docs/tmpl/pango-engine-shape.sgml
index d1aff7d0..478d667f 100644
--- a/docs/tmpl/pango-engine-shape.sgml
+++ b/docs/tmpl/pango-engine-shape.sgml
@@ -6,7 +6,9 @@ Rendering-system dependent script engines
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+The <firstterm>shape engines</firstterm> are rendering-system dependent
+engines that convert character strings into glyph strings.
+These engines are used in pango_shape().
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -14,6 +16,9 @@ Rendering-system dependent script engines
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT PangoEngineShape ##### -->
 <para>
 </para>
@@ -30,7 +35,7 @@ Rendering-system dependent script engines
 <!-- ##### MACRO PANGO_ENGINE_TYPE_SHAPE ##### -->
 <para>
 A string constant defining the engine type
-for <firstterm>shaping engines</firstterm>.
+for shaping engines.
 These engines derive from #PangoEngineShape.
 </para>
 
@@ -43,14 +48,6 @@ These engines derive from #PangoEngineShape.
 
 @name: 
 @prefix: 
-@\
-				       class_init:
-@\
-				       class_init:
-@\
-				       class_init:
-@\
-				       class_init:
 @class_init: 
 @instance_init: 
 
diff --git a/docs/tmpl/pango-renderer.sgml b/docs/tmpl/pango-renderer.sgml
index f5f2bd9c..c7e76813 100644
--- a/docs/tmpl/pango-renderer.sgml
+++ b/docs/tmpl/pango-renderer.sgml
@@ -18,6 +18,9 @@ destinations can be created.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT PangoRenderer ##### -->
 <para>
 
diff --git a/docs/tmpl/pangocairo.sgml b/docs/tmpl/pangocairo.sgml
index 93172ac4..e6e57650 100644
--- a/docs/tmpl/pangocairo.sgml
+++ b/docs/tmpl/pangocairo.sgml
@@ -139,6 +139,9 @@ int main (int argc, char **argv)
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT PangoCairoFontMap ##### -->
 <para>
 
diff --git a/docs/tmpl/pangofc-decoder.sgml b/docs/tmpl/pangofc-decoder.sgml
index ad033b6a..b8191c73 100644
--- a/docs/tmpl/pangofc-decoder.sgml
+++ b/docs/tmpl/pangofc-decoder.sgml
@@ -15,6 +15,9 @@ for handling a font that is encoded in a custom way.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT PangoFcDecoder ##### -->
 <para>
 
diff --git a/docs/tmpl/pangofc-font.sgml b/docs/tmpl/pangofc-font.sgml
index c87b2617..6bea63f4 100644
--- a/docs/tmpl/pangofc-font.sgml
+++ b/docs/tmpl/pangofc-font.sgml
@@ -31,6 +31,9 @@ Fontconfig-based backend involves deriving from both
 </variablelist>
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT PangoFcFont ##### -->
 <para>
 
diff --git a/docs/tmpl/pangofc-fontmap.sgml b/docs/tmpl/pangofc-fontmap.sgml
index 68a349f1..7e3c0ae1 100644
--- a/docs/tmpl/pangofc-fontmap.sgml
+++ b/docs/tmpl/pangofc-fontmap.sgml
@@ -31,6 +31,9 @@ Fontconfig-based backend involves deriving from both
 </variablelist>
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT PangoFcFontMap ##### -->
 <para>
 
diff --git a/docs/tmpl/scripts.sgml b/docs/tmpl/scripts.sgml
index f454678e..b2fddf84 100644
--- a/docs/tmpl/scripts.sgml
+++ b/docs/tmpl/scripts.sgml
@@ -16,6 +16,9 @@ and of ranges within a larger text string.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT PangoScriptIter ##### -->
 <para>
 
@@ -25,75 +28,78 @@ and of ranges within a larger text string.
 <!-- ##### ENUM PangoScript ##### -->
 <para>
 The #PangoScript enumeration identifies different writing
-systems. The values correspond to the names defined in the
-Unicode standard. (See <ulink
+systems. The values correspond to the names as defined in the
+Unicode standard.
+Note that new types may be added in the future. Applications should be ready
+to handle unknown values.
+See <ulink
 url="http://www.unicode.org/reports/tr24/">Unicode Standard Annex
-#24: Script names</ulink>).
+#24: Script names</ulink>.
 </para>
 
 @PANGO_SCRIPT_INVALID_CODE: a value never used for any Unicode character
 @PANGO_SCRIPT_COMMON: a character used by multiple different scripts
 @PANGO_SCRIPT_INHERITED: a mark glyph that takes its script from the
   base glyph to which it is attached.
-@PANGO_SCRIPT_ARABIC: 
-@PANGO_SCRIPT_ARMENIAN: 
-@PANGO_SCRIPT_BENGALI: 
-@PANGO_SCRIPT_BOPOMOFO: 
-@PANGO_SCRIPT_CHEROKEE: 
-@PANGO_SCRIPT_COPTIC: 
-@PANGO_SCRIPT_CYRILLIC: 
-@PANGO_SCRIPT_DESERET: 
-@PANGO_SCRIPT_DEVANAGARI: 
-@PANGO_SCRIPT_ETHIOPIC: 
-@PANGO_SCRIPT_GEORGIAN: 
-@PANGO_SCRIPT_GOTHIC: 
-@PANGO_SCRIPT_GREEK: 
-@PANGO_SCRIPT_GUJARATI: 
-@PANGO_SCRIPT_GURMUKHI: 
-@PANGO_SCRIPT_HAN: 
-@PANGO_SCRIPT_HANGUL: 
-@PANGO_SCRIPT_HEBREW: 
-@PANGO_SCRIPT_HIRAGANA: 
-@PANGO_SCRIPT_KANNADA: 
-@PANGO_SCRIPT_KATAKANA: 
-@PANGO_SCRIPT_KHMER: 
-@PANGO_SCRIPT_LAO: 
-@PANGO_SCRIPT_LATIN: 
-@PANGO_SCRIPT_MALAYALAM: 
-@PANGO_SCRIPT_MONGOLIAN: 
-@PANGO_SCRIPT_MYANMAR: 
-@PANGO_SCRIPT_OGHAM: 
-@PANGO_SCRIPT_OLD_ITALIC: 
-@PANGO_SCRIPT_ORIYA: 
-@PANGO_SCRIPT_RUNIC: 
-@PANGO_SCRIPT_SINHALA: 
-@PANGO_SCRIPT_SYRIAC: 
-@PANGO_SCRIPT_TAMIL: 
-@PANGO_SCRIPT_TELUGU: 
-@PANGO_SCRIPT_THAANA: 
-@PANGO_SCRIPT_THAI: 
-@PANGO_SCRIPT_TIBETAN: 
-@PANGO_SCRIPT_CANADIAN_ABORIGINAL: 
-@PANGO_SCRIPT_YI: 
-@PANGO_SCRIPT_TAGALOG: 
-@PANGO_SCRIPT_HANUNOO: 
-@PANGO_SCRIPT_BUHID: 
-@PANGO_SCRIPT_TAGBANWA: 
-@PANGO_SCRIPT_BRAILLE: 
-@PANGO_SCRIPT_CYPRIOT: 
-@PANGO_SCRIPT_LIMBU: 
-@PANGO_SCRIPT_OSMANYA: 
-@PANGO_SCRIPT_SHAVIAN: 
-@PANGO_SCRIPT_LINEAR_B: 
-@PANGO_SCRIPT_TAI_LE: 
-@PANGO_SCRIPT_UGARITIC: 
-@PANGO_SCRIPT_NEW_TAI_LUE: 
-@PANGO_SCRIPT_BUGINESE: 
-@PANGO_SCRIPT_GLAGOLITIC: 
-@PANGO_SCRIPT_TIFINAGH: 
-@PANGO_SCRIPT_SYLOTI_NAGRI: 
-@PANGO_SCRIPT_OLD_PERSIAN: 
-@PANGO_SCRIPT_KHAROSHTHI: 
+@PANGO_SCRIPT_ARABIC: 	Arabic
+@PANGO_SCRIPT_ARMENIAN: Armenian
+@PANGO_SCRIPT_BENGALI: 	Bengali
+@PANGO_SCRIPT_BOPOMOFO: Bopomofo
+@PANGO_SCRIPT_CHEROKEE: 	Cherokee
+@PANGO_SCRIPT_COPTIC: 	Coptic
+@PANGO_SCRIPT_CYRILLIC: 	Cyrillic
+@PANGO_SCRIPT_DESERET: 	Deseret
+@PANGO_SCRIPT_DEVANAGARI: 	Devanagari
+@PANGO_SCRIPT_ETHIOPIC: 	Ethiopic
+@PANGO_SCRIPT_GEORGIAN: 	Georgian
+@PANGO_SCRIPT_GOTHIC: 	Gothic
+@PANGO_SCRIPT_GREEK: 	Greek
+@PANGO_SCRIPT_GUJARATI: 	Gujarati
+@PANGO_SCRIPT_GURMUKHI: 	Gurmukhi
+@PANGO_SCRIPT_HAN: 	Han
+@PANGO_SCRIPT_HANGUL: 	Hangul
+@PANGO_SCRIPT_HEBREW: 	Hebrew
+@PANGO_SCRIPT_HIRAGANA: 	Hiragana
+@PANGO_SCRIPT_KANNADA: 	Kannada
+@PANGO_SCRIPT_KATAKANA: 	Katakana
+@PANGO_SCRIPT_KHMER: 	Khmer
+@PANGO_SCRIPT_LAO: 	Lao
+@PANGO_SCRIPT_LATIN: 	Latin
+@PANGO_SCRIPT_MALAYALAM: 	Malayalam
+@PANGO_SCRIPT_MONGOLIAN: 	Mongolian
+@PANGO_SCRIPT_MYANMAR: 	Myanmar
+@PANGO_SCRIPT_OGHAM: 	Ogham
+@PANGO_SCRIPT_OLD_ITALIC: 	Old Italic
+@PANGO_SCRIPT_ORIYA: 	Oriya
+@PANGO_SCRIPT_RUNIC: 	Runic
+@PANGO_SCRIPT_SINHALA: 	Sinhala
+@PANGO_SCRIPT_SYRIAC: 	Syriac
+@PANGO_SCRIPT_TAMIL: 	Tamil
+@PANGO_SCRIPT_TELUGU: 	Telugu
+@PANGO_SCRIPT_THAANA: 	Thaana
+@PANGO_SCRIPT_THAI: 	Thai
+@PANGO_SCRIPT_TIBETAN: 	Tibetan
+@PANGO_SCRIPT_CANADIAN_ABORIGINAL: 	Canadian Aboriginal
+@PANGO_SCRIPT_YI: 	Yi
+@PANGO_SCRIPT_TAGALOG: 	Tagalog
+@PANGO_SCRIPT_HANUNOO: 	Hanunoo
+@PANGO_SCRIPT_BUHID: 	Buhid
+@PANGO_SCRIPT_TAGBANWA: 	Tagbanwa
+@PANGO_SCRIPT_BRAILLE: 	Braille
+@PANGO_SCRIPT_CYPRIOT: 	Cypriot
+@PANGO_SCRIPT_LIMBU: 	Limbu
+@PANGO_SCRIPT_OSMANYA: 	Osmanya
+@PANGO_SCRIPT_SHAVIAN: 	Shavian
+@PANGO_SCRIPT_LINEAR_B: 	Linear B
+@PANGO_SCRIPT_TAI_LE: 	Tai Le
+@PANGO_SCRIPT_UGARITIC: 	Ugaritic
+@PANGO_SCRIPT_NEW_TAI_LUE: 	New Tai Lue
+@PANGO_SCRIPT_BUGINESE: 	Buginese
+@PANGO_SCRIPT_GLAGOLITIC: 	Glagolitic
+@PANGO_SCRIPT_TIFINAGH: 	Tifinagh
+@PANGO_SCRIPT_SYLOTI_NAGRI: 	Syloti Nagri
+@PANGO_SCRIPT_OLD_PERSIAN: 	Old Persian
+@PANGO_SCRIPT_KHAROSHTHI: 	Kharoshthi
 
 <!-- ##### MACRO PANGO_TYPE_SCRIPT ##### -->
 <para>
diff --git a/docs/tmpl/tab-stops.sgml b/docs/tmpl/tab-stops.sgml
index 757280ad..03ae3792 100644
--- a/docs/tmpl/tab-stops.sgml
+++ b/docs/tmpl/tab-stops.sgml
@@ -6,7 +6,8 @@ Structures for storing tab stops
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+Functions in this section are used to deal with #PangoTabArray objects
+that can be used to set tab stop positions in a #PangoLayout.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -14,6 +15,9 @@ Structures for storing tab stops
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT PangoTabArray ##### -->
 <para>
 A #PangoTabArray struct contains an array
diff --git a/docs/tmpl/text-attributes.sgml b/docs/tmpl/text-attributes.sgml
index ba17fed1..871494fb 100644
--- a/docs/tmpl/text-attributes.sgml
+++ b/docs/tmpl/text-attributes.sgml
@@ -18,6 +18,9 @@ of attributes applied to a portion of text.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### ENUM PangoAttrType ##### -->
 <para>
 The #PangoAttrType
@@ -28,14 +31,14 @@ values are given below. The type of structure used to store the
 attribute is listed in parentheses after the description.
 </para>
 
-@PANGO_ATTR_INVALID: 
+@PANGO_ATTR_INVALID: does not happen
 @PANGO_ATTR_LANGUAGE: language (#PangoAttrLanguage)
 @PANGO_ATTR_FAMILY: font family name list (#PangoAttrString)
 @PANGO_ATTR_STYLE: font slant style (#PangoAttrInt)
 @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 points divided by %PANGO_SCALE (#PangoAttrInt)
+@PANGO_ATTR_SIZE: font size in points scaled by %PANGO_SCALE (#PangoAttrInt)
 @PANGO_ATTR_FONT_DESC: font description (#PangoAttrFontDesc)
 @PANGO_ATTR_FOREGROUND: foreground color (#PangoAttrColor)
 @PANGO_ATTR_BACKGROUND: background color (#PangoAttrColor)
@@ -45,10 +48,10 @@ attribute is listed in parentheses after the description.
 @PANGO_ATTR_SHAPE: shape (#PangoAttrShape)
 @PANGO_ATTR_SCALE: font size scale factor (#PangoAttrFloat)
 @PANGO_ATTR_FALLBACK: whether fallback is enabled (#PangoAttrInt)
-@PANGO_ATTR_LETTER_SPACING: 
-@PANGO_ATTR_UNDERLINE_COLOR: 
-@PANGO_ATTR_STRIKETHROUGH_COLOR: 
-@PANGO_ATTR_ABSOLUTE_SIZE: 
+@PANGO_ATTR_LETTER_SPACING: letter spacing (#PangoAttrInt)
+@PANGO_ATTR_UNDERLINE_COLOR: underline color (#PangoAttrColor)
+@PANGO_ATTR_STRIKETHROUGH_COLOR: strikethrough color (#PangoAttrColor)
+@PANGO_ATTR_ABSOLUTE_SIZE: font size in pixels scaled by %PANGO_SCALE (#PangoAttrInt)
 
 <!-- ##### MACRO PANGO_TYPE_ATTR_TYPE ##### -->
 <para>
@@ -68,7 +71,7 @@ provided for #PangoAttribute.
 @type: the type ID for this attribute
 @copy: function to duplicate an attribute of this type (see pango_attribute_copy())
 @destroy: function to free an attribute of this type (see pango_attribute_destroy())
-@equal: 
+@equal: function to check two attributes of this type for equality (see pango_attribute_equal())
 
 <!-- ##### STRUCT PangoAttribute ##### -->
 <para>
@@ -147,9 +150,9 @@ impose shape restrictions.
 @attr: the common portion of the attribute
 @ink_rect: the ink rectangle to restrict to
 @logical_rect: the logical rectangle to restrict to
-@data: 
-@copy_func: 
-@destroy_func: 
+@data: user data set (see pango_attr_shape_new_with_data())
+@copy_func: copy function for the user data
+@destroy_func: destroy function for the user data
 
 <!-- ##### STRUCT PangoAttrSize ##### -->
 <para>
diff --git a/docs/tmpl/win32-fonts.sgml b/docs/tmpl/win32-fonts.sgml
index 17b9924b..e4a95d7f 100644
--- a/docs/tmpl/win32-fonts.sgml
+++ b/docs/tmpl/win32-fonts.sgml
@@ -6,7 +6,8 @@ Functions for shape engines to manipulate Win32 fonts
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+The macros and functions in this section are used to access fonts natively on
+Win32 systems and to render text in conjunction with Win32 APIs.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -14,6 +15,9 @@ Functions for shape engines to manipulate Win32 fonts
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### MACRO PANGO_RENDER_TYPE_WIN32 ##### -->
 <para>
 A string constant identifying the Win32 renderer. The associated quark (see
diff --git a/docs/tmpl/x-fonts.sgml b/docs/tmpl/x-fonts.sgml
index 875fa26b..7d358f25 100644
--- a/docs/tmpl/x-fonts.sgml
+++ b/docs/tmpl/x-fonts.sgml
@@ -9,7 +9,8 @@ Font handling and rendering with the deprecated X font backend
 The functions and macros in this section are for use with the old
 X font backend which used server-side bitmap fonts. This font backend
 is no longer supported, and attempts to use it will produce
-unpredictable results. Use the <link linkend="pango-Xft-Fonts-and-Rendering">Xft backend</link> instead.
+unpredictable results. Use the <link linkend="pango-Xft-Fonts-and-Rendering">Xft</link>
+or <link linkend="pango-Cairo-Rendering">Cairo</link> backend instead.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -17,6 +18,9 @@ unpredictable results. Use the <link linkend="pango-Xft-Fonts-and-Rendering">Xft
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### MACRO PANGO_RENDER_TYPE_X ##### -->
 <para>
 A string constant identifying the X renderer. The associated quark (see 
diff --git a/docs/tmpl/xft-fonts.sgml b/docs/tmpl/xft-fonts.sgml
index 00f345ae..9be166db 100644
--- a/docs/tmpl/xft-fonts.sgml
+++ b/docs/tmpl/xft-fonts.sgml
@@ -39,6 +39,9 @@ overring the #PangoXftRendererClass virtual functions
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT PangoXftFont ##### -->
 <para>
 #PangoXftFont is an implementation of #PangoFcFont using the Xft
diff --git a/examples/Makefile.am b/examples/Makefile.am
index 5a696c0d..3b8dfea7 100644
--- a/examples/Makefile.am
+++ b/examples/Makefile.am
@@ -13,7 +13,6 @@ TEST_TEXTS =			\
 
 EXTRA_DIST =			\
 	viewer-win32.c		\
-	makefile.msc		\
 	$(TEST_TEXTS)
 
 CLEANFILES = pangorc
diff --git a/pango/modules.c b/pango/modules.c
index df928690..e0369ca1 100644
--- a/pango/modules.c
+++ b/pango/modules.c
@@ -110,7 +110,7 @@ static GType pango_module_get_type (void);
  * type. The resulting map can be used to determine the engine
  * for each character.
  * 
- * Return value: 
+ * Return value: the suitable #PangoMap.
  **/
 PangoMap *
 pango_find_map (PangoLanguage *language,
diff --git a/pango/pango-coverage.c b/pango/pango-coverage.c
index c8f79d89..56777a85 100644
--- a/pango/pango-coverage.c
+++ b/pango/pango-coverage.c
@@ -165,7 +165,7 @@ pango_coverage_unref (PangoCoverage *coverage)
  * 
  * Determine whether a particular index is covered by @coverage
  * 
- * Return value: 
+ * Return value: the coverage level of @coverage for character @index_.
  **/
 PangoCoverageLevel
 pango_coverage_get (PangoCoverage *coverage,