updates.

Wed Feb  9 14:04:35 2000  Owen Taylor  <otaylor@redhat.com>

	* TODO: updates.

	* docs/*: Added some docs on font handling, both general
	and for X.

5 files changed, 173 insertions, 108 deletions

diff --git a/docs/pango-docs.sgml b/docs/pango-docs.sgml
index 26019c4d..9e0d724d 100644
--- a/docs/pango-docs.sgml
+++ b/docs/pango-docs.sgml
@@ -4,7 +4,8 @@
 <!entity pango-fonts SYSTEM "sgml/fonts.sgml">
 <!entity pango-coverage-maps SYSTEM "sgml/coverage-maps.sgml">
 <!entity pango-engines SYSTEM "sgml/engines.sgml">
-<!entity pango-x SYSTEM "sgml/pango-x.sgml">
+<!entity x-fonts SYSTEM "sgml/x-fonts.sgml">
+<!entity x-rendering SYSTEM "sgml/x-rendering.sgml">
 ]>
 <book>
   <bookinfo>
@@ -22,6 +23,7 @@
 
   <chapter id="pango-x">
     <title>Rendering under X with Pango</title>
-    &pango-x;
+    &x-fonts;
+    &x-rendering;
     </chapter>
 </book>
\ No newline at end of file
diff --git a/docs/pango-sections.txt b/docs/pango-sections.txt
index a40bf383..f68e34a5 100644
--- a/docs/pango-sections.txt
+++ b/docs/pango-sections.txt
@@ -48,8 +48,9 @@ pango_glyph_string_free
 <SECTION>
 <TITLE>Coverage Maps</TITLE>
 <FILE>coverage-maps</FILE>
-PangoCoverage
 PangoCoverageLevel
+PangoCoverage
+<SUBSECTION>
 pango_coverage_new
 pango_coverage_copy
 pango_coverage_destroy
@@ -66,13 +67,12 @@ PangoStyle
 PangoWeight
 PangoVariant
 PangoStretch
-PangoFont
-PangoFontClass
-PangoFontMap
-PangoFontMapClass
 pango_font_description_copy
 pango_font_descriptions_free
 pango_font_description_free
+<SUBSECTION>
+PangoFont
+PangoFontClass
 pango_font_init
 pango_font_ref
 pango_font_unref
@@ -81,6 +81,9 @@ pango_font_describe
 pango_font_get_coverage
 pango_font_get_data
 pango_font_set_data
+<SUBSECTION>
+PangoFontMap
+PangoFontMapClass
 pango_font_map_init
 pango_font_map_ref
 pango_font_map_unref
@@ -105,19 +108,24 @@ script_engine_unload
 </SECTION>
 
 <SECTION>
-<FILE>pango-x</FILE>
 <TITLE>X Rendering</TITLE>
-PangoXSubfont
+<FILE>x-rendering</FILE>
 PANGO_RENDER_TYPE_X
-PANGO_X_MAKE_GLYPH
-PANGO_X_GLYPH_SUBFONT
-PANGO_X_GLYPH_INDEX
 pango_x_get_context
-pango_x_load_font
 pango_x_render
 pango_x_extents
 pango_x_glyph_extents
+</SECTION>
+
+<SECTION>
+<TITLE>X Fonts</TITLE>
+<FILE>x-fonts</FILE>
+PangoXSubfont
+PANGO_X_MAKE_GLYPH
+PANGO_X_GLYPH_SUBFONT
+PANGO_X_GLYPH_INDEX
+pango_x_load_font
+pango_x_get_unknown_glyph
 pango_x_has_glyph
 pango_x_list_subfonts
 </SECTION>
-
diff --git a/docs/tmpl/coverage-maps.sgml b/docs/tmpl/coverage-maps.sgml
index eef7b24d..2347100a 100644
--- a/docs/tmpl/coverage-maps.sgml
+++ b/docs/tmpl/coverage-maps.sgml
@@ -2,11 +2,14 @@
 Coverage Maps
 
 <!-- ##### SECTION Short_Description ##### -->
-
+Unicode character range coverage storage.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+It is often necessary in Pango to determine if a paticular font can
+represent a particular character, and also how well it can represent
+that character. The #PangoCoverage is a data structure that is used
+to represent that information.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -14,21 +17,29 @@ Coverage Maps
 
 </para>
 
-<!-- ##### STRUCT PangoCoverage ##### -->
+<!-- ##### ENUM PangoCoverageLevel ##### -->
 <para>
-
+Used to indicate how well a font can represent a particular ISO 10646
+character point.
 </para>
 
+@PANGO_COVERAGE_NONE: The character is not representable with the font.
+@PANGO_COVERAGE_FALLBACK: The character is represented in a way that may be
+                          comprehensible but is not the correct graphical form.
+                          For instance, a Hangul character represented as a
+                          a sequence of Jamos, or a Latin transliteration of
+                          a Cyrillic word.
+@PANGO_COVERAGE_APPROXIMATE: The character is represented as the correct graphical
+                             form but not in the ideal fashion.
+@PANGO_COVERAGE_EXACT: The character is represented as the correct graphical form,
+                       in an attractive manner.
 
-<!-- ##### ENUM 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.
 </para>
 
-@PANGO_COVERAGE_NONE: 
-@PANGO_COVERAGE_FALLBACK: 
-@PANGO_COVERAGE_APPROXIMATE: 
-@PANGO_COVERAGE_EXACT: 
 
 <!-- ##### FUNCTION pango_coverage_new ##### -->
 <para>
diff --git a/docs/tmpl/fonts.sgml b/docs/tmpl/fonts.sgml
index c4180422..3c18a7da 100644
--- a/docs/tmpl/fonts.sgml
+++ b/docs/tmpl/fonts.sgml
@@ -8,11 +8,10 @@ Structures representing abstract fonts.
 <para>
 Pango supports a flexible architecture where a
 particular rendering architecture can supply an
-implementation of fonts. The #PangoFont and
-#PangoCFont structures represent an abstract
-rendering-system-indepent font, and a
-<firstterm>component</firstterm> of such a font,
-respectively.
+implementation of fonts. The #PangoFont structure
+representn an abstract rendering-system-indepent font.
+Pango provides routines to list available fonts, and
+to load a font of a given description.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -22,55 +21,87 @@ respectively.
 
 <!-- ##### STRUCT PangoFontDescription ##### -->
 <para>
-
+The #PangoFontDescription structure represents the description
+of an ideal font. These structures are used both to list
+what fonts are available on the system and also for specifying
+the characteristics of a font to load.
 </para>
 
-@family_name: 
-@style: 
-@variant: 
-@weight: 
-@stretch: 
+@family_name: the name of the font family.
+@style: the style (slant) of the font.
+@variant: the variant (normal or small caps) of the font.
+@weight: the weight (boldness) of the font.
+@stretch: the relative width of the font.
 
 <!-- ##### ENUM PangoStyle ##### -->
 <para>
-
+An enumeration specifying the various slant styles possible for a font.
 </para>
 
-@PANGO_STYLE_NORMAL: 
-@PANGO_STYLE_OBLIQUE: 
-@PANGO_STYLE_ITALIC: 
+@PANGO_STYLE_NORMAL: the font is upright.
+@PANGO_STYLE_OBLIQUE: the font is slanted, but in a roman style.
+@PANGO_STYLE_ITALIC: the font is slanted in an italic style.
 
 <!-- ##### ENUM PangoWeight ##### -->
 <para>
-
+An enumeration specifying the weight (boldness) of a font. This is a numerical
+value ranging from 100 to 900, but there are two predefined values:
 </para>
 
-@PANGO_WEIGHT_NORMAL: 
-@PANGO_WEIGHT_BOLD: 
+@PANGO_WEIGHT_NORMAL: the default weight (= 400)
+@PANGO_WEIGHT_BOLD: the bold weight (= 700)
 
 <!-- ##### ENUM PangoVariant ##### -->
 <para>
-
+An enumeration specifying capitalization variant of the font.
 </para>
 
-@PANGO_VARIANT_NORMAL: 
-@PANGO_VARIANT_SMALL_CAPS: 
+@PANGO_VARIANT_NORMAL: A normal font.
+@PANGO_VARIANT_SMALL_CAPS: A font with the lower case characters
+  replaced by smaller variants of the capital characters.
 
 <!-- ##### ENUM PangoStretch ##### -->
 <para>
-
+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_NORMAL: 
+@PANGO_STRETCH_NORMAL: the normal width
 @PANGO_STRETCH_SEMI_EXPANDED: 
 @PANGO_STRETCH_EXPANDED: 
 @PANGO_STRETCH_EXTRA_EXPANDED: 
 @PANGO_STRETCH_ULTRA_EXPANDED: 
 
+<!-- ##### FUNCTION pango_font_description_copy ##### -->
+<para>
+
+</para>
+
+@desc: 
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_font_descriptions_free ##### -->
+<para>
+
+</para>
+
+@descs: 
+@n_descs: 
+
+
+<!-- ##### FUNCTION pango_font_description_free ##### -->
+<para>
+
+</para>
+
+@desc: 
+
+
 <!-- ##### STRUCT PangoFont ##### -->
 <para>
 The #PangoFont structure is used to represent
@@ -85,21 +116,13 @@ pango_font_init() on the structure.
 </para>
 <para>
 The #PangoFont structure contains one member
-that may be accessed by derived classes:
-
-<informaltable pgwide=1 frame="none" role="struct">
-<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
-<tbody>
-
-<row>
-<entry>#PangoFontClass *klass;</entry>
-<entry>a pointer to the <firstterm>class structure</firstterm>
-       for this font.</entry>
-</row>
-</tbody></tgroup></informaltable>
+which the implementation fills in:
 </para>
 
-@klass: 
+@klass: a pointer to the <firstterm>class structure</firstterm>
+        for this font. People using a #PangoFont should
+        not directly access this member; they should use the
+        appropriate wrapper functions.
 
 <!-- ##### STRUCT PangoFontClass ##### -->
 <para>
@@ -119,45 +142,13 @@ It contains the following member:
 </tbody></tgroup></informaltable>
 </para>
 
-
-<!-- ##### STRUCT PangoFontMap ##### -->
-<para>
-
-</para>
-
-@klass: 
-
-<!-- ##### STRUCT PangoFontMapClass ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### FUNCTION pango_font_description_copy ##### -->
-<para>
-
-</para>
-
-@desc: 
-@Returns: 
-
-
-<!-- ##### FUNCTION pango_font_descriptions_free ##### -->
-<para>
-
-</para>
-
-@descs: 
-@n_descs: 
-
-
-<!-- ##### FUNCTION pango_font_description_free ##### -->
-<para>
-
-</para>
-
-@desc: 
-
+@destroy: a function to free the font structure and associated resources.
+@describe: a function to describe the characteristics of a font. See
+           pango_font_describe().
+@get_coverage: A function to get a coverage map for the font.
+               See pango_font_get_coverage().
+@find_shaper: A function to find the shaper for a particular character 
+              point. See pango_font_find_shaper.
 
 <!-- ##### FUNCTION pango_font_init ##### -->
 <para>
@@ -211,6 +202,7 @@ It contains the following member:
 </para>
 
 @font: 
+@lang: 
 @Returns: 
 
 
@@ -235,6 +227,37 @@ It contains the following member:
 @destroy_func: 
 
 
+<!-- ##### STRUCT PangoFontMap ##### -->
+<para>
+The #PangoFontMap represents the set of fonts available for a
+particular rendering system. This is a virtual object with
+implementations being specific to particular rendering systems.  To
+create an implementation of a #PangoFontMap, the rendering-system
+specific code should malloc a larger structure that contains a nested
+#PangoFontMap, fill in the klass member of the nested #PangoFontMap with a
+pointer to a appropriate #PangoFontMapClass, then call
+pango_font_map_init() on the structure.
+</para>
+<para>
+The #PangoFont structure contains one member which the implementation fills in:
+</para>
+
+@klass: a pointer to the <firstterm>class structure</firstterm>
+        for this font map. People using a #PangoFontMap should
+        not directly access this member; they should use the
+        appropriate wrapper functions.
+
+<!-- ##### STRUCT PangoFontMapClass ##### -->
+<para>
+The #PangoFontMapClass structure holds the virtual functions for
+a particular #PangoFontMap implementation.
+</para>
+
+@destroy: a function to free the font map structure and associated resources.
+@load_font: a function to load a font with a given description. See
+            pango_font_map_load_font()
+@list_fonts: A function to list available fonts. See pango_font_map_list_fonts()
+
 <!-- ##### FUNCTION pango_font_map_init ##### -->
 <para>
 
diff --git a/docs/tmpl/pango-unused.sgml b/docs/tmpl/pango-unused.sgml
index b17053da..24361688 100644
--- a/docs/tmpl/pango-unused.sgml
+++ b/docs/tmpl/pango-unused.sgml
@@ -54,6 +54,30 @@ indices.
 
 @string: 
 
+<!-- ##### FUNCTION pango_x_load_xlfd ##### -->
+<para>
+
+</para>
+
+@font: 
+@xlfd: 
+@Returns: 
+
+<!-- ##### SECTION ./tmpl/pango-x.sgml:Title ##### -->
+X Rendering
+
+
+<!-- ##### SECTION ./tmpl/pango-x.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/pango-x.sgml:Short_Description ##### -->
+Functions for rendering and measuring glyphs on
+the X Window system.
+
+
 <!-- ##### FUNCTION g_glyph_string_new ##### -->
 <para>
 
@@ -61,25 +85,22 @@ indices.
 
 @Returns: 
 
-<!-- ##### FUNCTION pango_x_list_cfonts ##### -->
+<!-- ##### SECTION ./tmpl/pango-x.sgml:Long_Description ##### -->
 <para>
 
 </para>
 
-@font: 
-@charsets: 
-@n_charsets: 
-@xlfds: 
-@n_xlfds: 
 
-<!-- ##### FUNCTION pango_x_load_xlfd ##### -->
+<!-- ##### FUNCTION pango_x_list_cfonts ##### -->
 <para>
 
 </para>
 
 @font: 
-@xlfd: 
-@Returns: 
+@charsets: 
+@n_charsets: 
+@xlfds: 
+@n_xlfds: 
 
 <!-- ##### STRUCT PangoCFontClass ##### -->
 <para>