Add documentation for attributes.

Tue Feb 15 02:35:56 2000  Owen Taylor  <otaylor@redhat.com>

	* docs/**: Add documentation for attributes.

	* Makefile.am libpango/pango-attributes.[ch]: Finish initial
	  implementation of attributes APIs.

4 files changed, 413 insertions, 0 deletions

diff --git a/docs/pango-docs.sgml b/docs/pango-docs.sgml
index 9e0d724d..a6e75d8c 100644
--- a/docs/pango-docs.sgml
+++ b/docs/pango-docs.sgml
@@ -2,6 +2,7 @@
 <!entity pango-main SYSTEM "sgml/main.sgml">
 <!entity pango-glyphs SYSTEM "sgml/glyphs.sgml">
 <!entity pango-fonts SYSTEM "sgml/fonts.sgml">
+<!entity pango-text-attributes SYSTEM "sgml/text-attributes.sgml">
 <!entity pango-coverage-maps SYSTEM "sgml/coverage-maps.sgml">
 <!entity pango-engines SYSTEM "sgml/engines.sgml">
 <!entity x-fonts SYSTEM "sgml/x-fonts.sgml">
@@ -17,6 +18,7 @@
     &pango-main;
     &pango-glyphs;
     &pango-fonts;
+    &pango-text-attributes;
     &pango-coverage-maps;
     &pango-engines;
   </chapter>
diff --git a/docs/pango-sections.txt b/docs/pango-sections.txt
index e628cc4f..12540f28 100644
--- a/docs/pango-sections.txt
+++ b/docs/pango-sections.txt
@@ -95,6 +95,47 @@ pango_font_map_list_fonts
 </SECTION>
 
 <SECTION>
+<TITLE>Text Attributes</TITLE>
+<FILE>text-attributes</FILE>
+PangoAttrType
+PangoAttrClass
+PangoAttribute
+PangoAttrString
+PangoAttrColor
+PangoAttrInt
+pango_attr_type_register
+pango_attribute_copy
+pango_attribute_compare
+pango_attribute_destroy
+<SUBSECTION>
+pango_attr_lang_new
+pango_attr_family_new
+pango_attr_style_new
+pango_attr_variant_new
+pango_attr_stretch_new
+pango_attr_weight_new
+pango_attr_size_new
+pango_attr_foreground_new
+pango_attr_background_new
+pango_attr_strikethrough_new
+pango_attr_underline_new
+pango_attr_rise_new
+<SUBSECTION>
+PangoAttrList
+pango_attr_list_new
+pango_attr_list_ref
+pango_attr_list_unref
+pango_attr_list_insert
+pango_attr_list_change
+pango_attr_list_get_iterator
+PangoAttrIterator
+pango_attr_iterator_next
+pango_attr_iterator_get
+pango_attr_iterator_get_font
+pango_attr_iterator_destroy
+</SECTION>
+
+<SECTION>
 <TITLE>Engines</TITLE>
 <FILE>engines</FILE>
 PangoEngineInfo
diff --git a/docs/tmpl/pango-unused.sgml b/docs/tmpl/pango-unused.sgml
index 24361688..c86590dd 100644
--- a/docs/tmpl/pango-unused.sgml
+++ b/docs/tmpl/pango-unused.sgml
@@ -78,6 +78,14 @@ Functions for rendering and measuring glyphs on
 the X Window system.
 
 
+<!-- ##### FUNCTION pango_attribute_register_type ##### -->
+<para>
+
+</para>
+
+@name: 
+@Returns: 
+
 <!-- ##### FUNCTION g_glyph_string_new ##### -->
 <para>
 
diff --git a/docs/tmpl/text-attributes.sgml b/docs/tmpl/text-attributes.sgml
new file mode 100644
index 00000000..4ab6a762
--- /dev/null
+++ b/docs/tmpl/text-attributes.sgml
@@ -0,0 +1,362 @@
+<!-- ##### SECTION Title ##### -->
+Text Attributes
+
+<!-- ##### SECTION Short_Description ##### -->
+Font and other attributes for annotating text.
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+Attributed text is used in a number of places in Pango. It
+is used as the input to the itemization process and also when
+creating a #PangoLayout. The data types and functions in
+this section are used to represent and manipulate sets
+of attributes applied to a portion of text.
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### ENUM PangoAttrType ##### -->
+<para>
+distinguishes between different types of attributes. Along with the
+predefined values, it is possible to allocate additional values
+for custom attributes using pango_attr_register_type(). The predefined
+values are given below. The type of structure used to store the
+attribute is listed in parentheses after the description.
+</para>
+
+@PANGO_ATTR_LANG: language tag (#PangoAttrString)
+@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 1000th's of a point (#PangoAttrInt)
+@PANGO_ATTR_FOREGROUND: foreground color (#PangoAttrColor)
+@PANGO_ATTR_BACKGROUND: background color (#PangoAttrColor)
+@PANGO_ATTR_UNDERLINE: whether the text has an underline (#PangoAttrInt)
+@PANGO_ATTR_STRIKETHROUGH: whether the text is struck-through (#PangoAttrInt)
+@PANGO_ATTR_RISE: baseline displacement (#PangoAttrInt)
+
+<!-- ##### STRUCT PangoAttrClass ##### -->
+<para>
+The #PangoAttrClass structure stores the type and operations for
+a particular type of attribute. The functions in this structure should
+not be called directly. Instead, one should use the wrapper functions
+provided for #PangoAttribute.
+</para>
+
+@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())
+@compare: function to compare two attributes of this type (see pango_attribute_compare())
+
+<!-- ##### STRUCT PangoAttribute ##### -->
+<para>
+The #PangoAttribute structure represents the common portions of all
+attributes. Particular types of attributes include this structure
+as their initial portion. The common portion of the attribute holds
+the range to which the value in the type-specific part of the attribute
+applies. 
+</para>
+
+@klass: the class structure holding information about the type of the attribute
+@start_index: the start index of the range.
+@end_index: end index of the range. The character at this index is not
+            included in the range.
+
+<!-- ##### STRUCT PangoAttrString ##### -->
+<para>
+The #PangoAttrString structure is used to represent attributes with
+a string value.
+</para>
+
+@attr: the common portion of the attribute
+@value: the value of the attribute
+
+<!-- ##### STRUCT PangoAttrColor ##### -->
+<para>
+The #PangoAttrString structure is used to represent attributes that
+are colors.
+</para>
+
+@attr: the common portion of the attribute
+@red: the red value, in the range 0 to 65535
+@green: the green value
+@blue: the blue value
+
+<!-- ##### STRUCT PangoAttrInt ##### -->
+<para>
+The #PangoAttrString structure is used to represent attributes with
+a integer or enumeration value.
+</para>
+
+@attr: the common portion of the attribute
+@value: the value of the attribute
+
+<!-- ##### FUNCTION pango_attr_type_register ##### -->
+<para>
+
+</para>
+
+@name: 
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_attribute_copy ##### -->
+<para>
+
+</para>
+
+@attr: 
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_attribute_compare ##### -->
+<para>
+
+</para>
+
+@attr1: 
+@attr2: 
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_attribute_destroy ##### -->
+<para>
+
+</para>
+
+@attr: 
+
+
+<!-- ##### FUNCTION pango_attr_lang_new ##### -->
+<para>
+
+</para>
+
+@lang: 
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_attr_family_new ##### -->
+<para>
+
+</para>
+
+@family: 
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_attr_style_new ##### -->
+<para>
+
+</para>
+
+@style: 
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_attr_variant_new ##### -->
+<para>
+
+</para>
+
+@variant: 
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_attr_stretch_new ##### -->
+<para>
+
+</para>
+
+@stretch: 
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_attr_weight_new ##### -->
+<para>
+
+</para>
+
+@weight: 
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_attr_size_new ##### -->
+<para>
+
+</para>
+
+@size: 
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_attr_foreground_new ##### -->
+<para>
+
+</para>
+
+@red: 
+@green: 
+@blue: 
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_attr_background_new ##### -->
+<para>
+
+</para>
+
+@red: 
+@green: 
+@blue: 
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_attr_strikethrough_new ##### -->
+<para>
+
+</para>
+
+@strikethrough: 
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_attr_underline_new ##### -->
+<para>
+
+</para>
+
+@underline: 
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_attr_rise_new ##### -->
+<para>
+
+</para>
+
+@rise: 
+@Returns: 
+
+
+<!-- ##### STRUCT PangoAttrList ##### -->
+<para>
+The #PangoAttrList structure represents a list of attributes
+that apply to a section of text. The attributes are, in general,
+allowed to overlap in an arbitrary fashion, however, if the
+attributes are manipulated only through pango_attr_list_change(),
+the overlap between properties will meet stricter criteria.
+</para>
+<para>
+Since the #PangoAttrList structure is stored as a linear list,
+it is not suitable for storing attributes for large amounts
+of text. In general, you should not use a single #PangoAttrList
+for more than one paragraph of text.
+</para>
+
+
+<!-- ##### FUNCTION pango_attr_list_new ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_attr_list_ref ##### -->
+<para>
+
+</para>
+
+@list: 
+
+
+<!-- ##### FUNCTION pango_attr_list_unref ##### -->
+<para>
+
+</para>
+
+@list: 
+
+
+<!-- ##### FUNCTION pango_attr_list_insert ##### -->
+<para>
+
+</para>
+
+@list: 
+@attr: 
+
+
+<!-- ##### FUNCTION pango_attr_list_change ##### -->
+<para>
+
+</para>
+
+@list: 
+@attr: 
+
+
+<!-- ##### FUNCTION pango_attr_list_get_iterator ##### -->
+<para>
+
+</para>
+
+@list: 
+@Returns: 
+
+
+<!-- ##### STRUCT PangoAttrIterator ##### -->
+<para>
+The #PangoAttrIterator structure is used to represent an
+iterator through a #PangoList. A new iterator is created
+with pango_attr_list_get_iterator(). Once the iterator
+is created, it can be advanced through the style changes
+in the text using pango_attr_iterator_next(). At each
+style change, the attributes currently in effect can
+be queried.
+</para>
+
+
+<!-- ##### FUNCTION pango_attr_iterator_next ##### -->
+<para>
+
+</para>
+
+@iterator: 
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_attr_iterator_get ##### -->
+<para>
+
+</para>
+
+@iterator: 
+@type: 
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_attr_iterator_destroy ##### -->
+<para>
+
+</para>
+
+@iterator: 
+
+
+<!-- ##### FUNCTION pango_attr_iterator_get_font ##### -->
+<para>
+
+</para>
+
+@iterator: 
+@base: 
+@current: 
+
+