PyGTK 2.4 and Pango. Also add description of Child Properties.

	* pygtk-introduction.xml Update the introduction re: PyGTK 2.4
	and Pango. Also add description of Child Properties.

1 files changed, 78 insertions, 42 deletions

diff --git a/docs/reference/pygtk-introduction.xml b/docs/reference/pygtk-introduction.xml
index 77b2fb04..78a5a6f9 100644
--- a/docs/reference/pygtk-introduction.xml
+++ b/docs/reference/pygtk-introduction.xml
@@ -1,42 +1,45 @@
 <?xml version="1.0" standalone="no"?>
-<!DOCTYPE chpater PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
     "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
 
   <chapter id="pygtk-introduction">
     <title>Introduction</title>
 
     <para>This document describes most of the <literal>PyGTK</literal>
-version 2.0 classes and their methods and associated functions. Deprecated
-classes, functions and methods have been specifically left out of this
-reference. I have attempted to document as much of the
-<literal>PyGTK</literal> <literal>API</literal> as I can but there are
-undoubtedly errors and omissions. If you discover any of these please send
-me an email at <email><ulink
-url="mailto:finlay@moeraki.com">finlay@moeraki.com</ulink></email>. Specific areas that have not been documented include:</para>
+version 2.0 through 2.4 classes and their methods and associated
+functions. Deprecated classes, functions and methods have been specifically
+left out of this reference though classes that have become deprecated since
+PyGTK 2.0 have been left in but annotated with a deprecation warning. I have
+attempted to document as much of the <literal>PyGTK</literal>
+<literal>API</literal> as I can but there are undoubtedly errors and
+omissions. If you discover any of these please send me email at
+<email><ulink
+url="mailto:finlay@moeraki.com">finlay@moeraki.com</ulink></email>. Specific
+areas that have not been documented include:</para>
 
     <itemizedlist>
       <listitem>
-	<simpara>The GObject classes other than GObject</simpara>
-      </listitem>
-      <listitem>
 	<simpara>The ATK classes</simpara>
       </listitem>
       <listitem>
-	<simpara>The Pango classes</simpara>
-      </listitem>
-      <listitem>
 	<simpara>The GladeXML class</simpara>
       </listitem>
     </itemizedlist>
 
     <para>This reference describes the API for <literal>PyGTK</literal> as
-of version 1.99.16+ and assumes that the additional API changes for version
-2.0 will be minor. There will undoubtedly be changes that are not reflected
-in this reference. Likewise the differences in the API between version
-1.99.16+ and previous versions are not covered in this reference. The source
-code must be consulted if this reference and your version of
-<literal>PyGTK</literal> seem to differ. You are encouraged to use the
-latest version of <literal>PyGTK</literal> that is available. See the <ulink
+of version 2.3.92+ and assumes that the additional API changes for version
+2.4 will be minor. There will undoubtedly be changes that are not reflected
+in this reference. The differences in the API between version 2.0 and
+previous versions are denoted in this reference with a Note that describes
+the availability of the obejct, constructor, method or function. Any of
+these that do not have a notation can be assumed to be available in all
+versions of PyGTK from 2.0 and up. In the case of properties and signals the
+availability is dependent on the version of the underlying GTK+, GDK or
+Pango libraries. These will be annotated appropriately in a similar
+fashion. The source code must be consulted if this reference and your
+version of <literal>PyGTK</literal> seem to differ. You are encouraged to
+use the latest version of <literal>PyGTK</literal> that is available. See
+the <ulink
 url="http://www.daa.com.au/~james/software/pygtk/"><literal>PyGTK</literal>
 homepage</ulink> for more information.</para>
 
@@ -44,10 +47,10 @@ homepage</ulink> for more information.</para>
 <literal>PyGTK</literal> module (that correspponds to the underlying
 <literal>GTK+</literal> library) containing the class descriptions. The
 second chapter illustrates the <literal>PyGTK</literal> class hierarchy
-covering the gobject, gtk and gtk.gdk modules.</para>
+covering the gobject, gtk, gtk.gdk and pango modules.</para>
 
     <para>The class descriptions are arranged alphabetically
-within the chapters. Currently there are three module chapters:</para>
+within the chapters. Currently there are four module chapters:</para>
 
     <variablelist>
       <varlistentry>
@@ -78,12 +81,24 @@ provide an abstract interface to the underlying window system (either X
 Window System or Microsoft Windows).</simpara>
 	</listitem>
       </varlistentry>
+      <varlistentry>
+	<term>The&nbsp;<literal>pango</literal>&nbsp;module</term>
+	<listitem>
+	  <simpara>The classes that are included in the
+<literal>pango</literal> module of <literal>PyGTK</literal>. These classes
+provide access to the Pango text layout and rendering engines. PyGTK
+supports a subset of the full Pango capability: mainly the high level layout
+capabilites exposed by the pango.Layout objects. The low level rendering
+capabilites have not been exposed mostly because there isn't a full GObject
+interface to the underlying Pango data structures. It's also likely that the
+rendering capabilities require more performance that Python can
+provide.</simpara>
+	</listitem>
+      </varlistentry>
     </variablelist>
 
-    <para>The <literal>pango</literal> and <literal>atk</literal> module
-classes will be added in a later version of this Reference. Also a more
-complete description of the <literal>gobject</literal> module classes will
-be provided.</para>
+    <para>The <literal>atk</literal> module classes will be added in a later
+version of this Reference.</para>
 
     <sect1 id="pygtk-reference-format">
       <title>Reference Page Format</title>
@@ -95,25 +110,29 @@ will have a subset of the following sections:</para>
     <variablelist>
       <varlistentry>
 	<term>Name</term>
-	<listitem><simpara>The name and a one-line description of the
+	<listitem>
+	    <simpara>The name and a one-line description of the
 class.</simpara>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term>Synopsis</term>
-	<listitem><simpara>A synopsis of the class and its methods and
+	<listitem>
+	    <simpara>A synopsis of the class and its methods and
 optionally a list of associated functions.</simpara>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term>Ancestry</term>
-	<listitem><simpara>The list of the parent classes of the class. This
+	<listitem>
+	    <simpara>The list of the parent classes of the class. This
 section may not be present in all class descriptions.</simpara>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term>Properties</term>
- 	<listitem><simpara>A list of the properties (internal state)
+ 	<listitem>
+	    <simpara>A list of the properties (internal state)
 supported by the class. This section may not be present in all classes. The
 property descriptons include the name, the access operations (e.g. Read,
 Write), and a brief description. Properties are accessed using the <link
@@ -126,17 +145,29 @@ section may not be present in all class descriptions.</simpara>
       </varlistentry>
       <varlistentry>
 	<term>Style&nbsp;Properties</term>
-	<listitem><simpara>A list of style properties supported by the
+	  <listitem>
+	    <simpara>A list of style properties supported by the
 class. Similar to the properties (described above) the style properties hold
 information about the style of a widgets e.g. border style, shadow type,
 etc. Most widgets do not support style properties so this section is not
-present in most class descriptions. Currently <literal>PyGTK</literal> has
-no way of accessing these properties.</simpara>
+present in most class descriptions. Only PyGTK 2.4 has the ability to access
+style properties.</simpara>
+	</listitem>
+      </varlistentry>
+      <varlistentry>
+	<term>Child&nbsp;Properties</term>
+	  <listitem>
+	    <simpara>A list of child properties supported by the
+class. Similar to the properties (described above) the child properties hold
+information about the properties of a widget's child widget. Only container
+widgets support child properties so this section is not present in most
+class descriptions.</simpara>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term>Attributes</term>
-	<listitem><simpara>A set of internal object state data accessible as
+	<listitem>
+	    <simpara>A set of internal object state data accessible as
 Python attributes (e.g. object.attr). The attribute descriptions include a
 name by which the attribute data is accessed, the access mode (e.g. Read,
 Write), and a brief description of the attribute. Most
@@ -146,7 +177,8 @@ is not present in most class descriptions.</simpara>
       </varlistentry>
       <varlistentry>
 	<term>Signal&nbsp;Prototypes</term>
-	<listitem><simpara>A list of the signals supported by the class
+	<listitem>
+	    <simpara>A list of the signals supported by the class
 including the signal name and a synopsis of the signal handler function
 prototype. This section may not be present in all class descriptions; most
 <literal>gtk.gdk</literal> classes do not support signals.</simpara>
@@ -160,7 +192,8 @@ the methods supported by the class.</simpara>
       </varlistentry>
       <varlistentry>
 	<term>Constructor</term>
-	<listitem><simpara>The description of the class object constructor
+	<listitem>
+	    <simpara>The description of the class object constructor
 including the synopsis with brief parameter descriptions and a description
 of th use of the constructor. There may be more than one constructor
 description if the constructor supports different parameter lists. This
@@ -169,7 +202,8 @@ section may not be present in all class descriptions.</simpara>
       </varlistentry>
       <varlistentry>
 	<term>Methods</term>
-	<listitem><simpara>A list of methods supported by the class. Each
+	<listitem>
+	    <simpara>A list of methods supported by the class. Each
 method description includes: a synopsis of the method and its parameters as
 well as a brief description of each parameter and return value (if any);
 and, a description of the use of the method.</simpara>
@@ -177,7 +211,8 @@ and, a description of the use of the method.</simpara>
       </varlistentry>
       <varlistentry>
 	<term>Functions</term>
-	<listitem><simpara>A list of related functions. Each function
+	<listitem>
+	    <simpara>A list of related functions. Each function
 description includes a synopsis of the function and its parameters and
 return value (if any), and a description of the use of the
 function.</simpara>
@@ -185,7 +220,8 @@ function.</simpara>
       </varlistentry>
       <varlistentry>
 	<term>Signals</term>
-	<listitem><simpara>A list of signals including a synopsis of the
+	<listitem>
+	    <simpara>A list of signals including a synopsis of the
 signal handler prototype function with its parameters and return value (if
 any). The signal emission conditions are briefly described. This section is
 not present in all class descriptions; specifically, the
@@ -223,7 +259,7 @@ gtk.Button(stock=None, label="Cancel")
 </programlisting>
 
     <para>Parameters that are not keyword parameters are displayed in
-<emphasis>italic</emphasis> and must be specified positionally but also may
+<emphasis>italic</emphasis> and must be specified positionally but may also
 be optional.</para>
 
     </sect1>
@@ -231,7 +267,7 @@ be optional.</para>
     <sect1 id="pygtk-reference-copyright">
       <title>Copyright and License Notice</title>
 
-      <para>The PyGTK 2.0 Reference is Copyright (C) 2003 John
+      <para>The PyGTK 2.0 Reference is Copyright (C) 2004 John
 Finlay.</para>
 
       <para>This work is licensed under the Creative Commons