Output xref links for unknown links.

	* docs/xsl/html.xsl: Output xref links for unknown links.

	* docs/xsl/ref-html-style.xsl: Include refsect1 and refsect2 in
	indexed items but only ig they have ids.

	* configure.ac (AC_CONFIG_FILES) : Add docs/reference/version.xml

	* docs/reference/pygobject-ref.xml: Add pygobject-introduction.xml
	and version and builddate entities. Remove commented out items.

	* docs/Makefile.am: Add reference/pygobject-introduction.xml and
	 reference/version.xml.in

1 files changed, 239 insertions, 0 deletions

diff --git a/docs/reference/pygobject-introduction.xml b/docs/reference/pygobject-introduction.xml
new file mode 100644
index 0000000..a139646
--- /dev/null
+++ b/docs/reference/pygobject-introduction.xml
@@ -0,0 +1,239 @@
+<?xml version="1.0" standalone="no"?>
+<!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="pygobject-introduction">
+  <title>Introduction</title>
+
+  <para>This document describes many of the <literal>PyGObject</literal>
+  version 2.12 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 PyGObject 2.0 have been left in but annotated with a
+  deprecation warning. I have attempted to document as much of the
+  <literal>PyGObject</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> or file
+  a bug report at <ulink
+  url="http://bugzilla.gnome.org">bugzilla.gnome.org</ulink> for the
+  <literal>pygobject</literal> project. Specific areas that have not been
+  documented include:</para>
+
+  <itemizedlist>
+    <listitem>
+      <simpara>The GParamSpec class</simpara>
+    </listitem>
+  </itemizedlist>
+
+  <para>This reference describes the API for <literal>PyGObject</literal> as
+  of version 2.11.0+ and assumes that the additional API changes for version
+  2.12 will not be significant. 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 object, constructor, method or
+  function. Any of these that do not have a notation can be assumed to be
+  available in all versions of PyGObject from 2.0 and up. The source code
+  must be consulted if this reference and your version of
+  <literal>PyGObject</literal> seem to differ. You are encouraged to use the
+  latest version of <literal>PyGObject</literal> that is available. See the
+  <ulink url="http://www.pygtk.org"><literal>PyGTK</literal>
+  homepage</ulink> for more information and more resources on how to use
+  PyGObject as well as help in its development.</para>
+
+  <para> The Reference contains a chapter for each
+  <literal>PyGObject</literal> module containing the class descriptions. The
+  class descriptions are arranged alphabetically within the
+  chapters. Currently there is one module chapter:</para>
+
+  <variablelist>
+    <varlistentry>
+      <term>The&nbsp;<literal>gobject</literal>&nbsp;module</term>
+      <listitem><simpara>The classes that are included in the
+<literal>gobject</literal> module of <literal>PyGObject</literal> and are
+accessed similar to: gobject.GObject. These classes are the base object
+classes that the <literal>gtk</literal> and <literal>gtk.gdk</literal>
+module classes are built on.</simpara>
+      </listitem>
+    </varlistentry>
+  </variablelist>
+
+<!--
+  <sect1>
+    <title>Major Changes since Version 2.11</title>
+
+    <para>The major changes in this document since version 2.11
+    include:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para></para>
+      </listitem>
+    </itemizedlist>
+
+  </sect1>
+-->
+
+  <sect1 id="pygobject-reference-format">
+    <title>Reference Page Format</title>
+
+    <para>Each <literal>PyGObject</literal> class is described in a reference
+page that has a number of sections in a fixed format. Each reference page
+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
+class.</simpara>
+	</listitem>
+      </varlistentry>
+      <varlistentry>
+	<term>Synopsis</term>
+	<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
+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)
+supported by the class. This section may not be present in all classes. The
+property descriptions include the name, the access operations (e.g. Read,
+Write), and a brief description. Properties are accessed using the <link
+linkend="method-gobject--set-property"><methodname>gobject.set_property</methodname>()</link> 
+and <link
+linkend="method-gobject--get-property"><methodname>gobject.get_property</methodname>()</link> 
+methods that are available to every <literal>PyGObject</literal> object. This
+section may not be present in all class descriptions.</simpara>
+	</listitem>
+      </varlistentry>
+      <varlistentry>
+	<term>Attributes</term>
+	<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
+	  <literal>PyGObject</literal> classes do not support attributes so
+	  this section is not present in most class descriptions.</simpara>
+	</listitem>
+      </varlistentry>
+      <varlistentry>
+	<term>Signal&nbsp;Prototypes</term>
+	<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.</simpara>
+	</listitem>
+      </varlistentry>
+      <varlistentry>
+	<term>Description</term>
+	<listitem><simpara>A description of the class and possibly some of
+	the methods supported by the class.</simpara>
+	</listitem>
+      </varlistentry>
+      <varlistentry>
+	<term>Constructor</term>
+	<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 section may not be present in all class
+	  descriptions.</simpara>
+	</listitem>
+      </varlistentry>
+      <varlistentry>
+	<term>Methods</term>
+	<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>
+	</listitem>
+      </varlistentry>
+      <varlistentry>
+	<term>Functions</term>
+	<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>
+	</listitem>
+      </varlistentry>
+      <varlistentry>
+	<term>Signals</term>
+	<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 <literal>gtk.gdk</literal> classes do not
+	  usually support signals.</simpara>
+	</listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>The function and method synopsis parameters are displayed in
+    <emphasis role="bold">bold</emphasis> to denote Python keyword
+    parameters.  Also if the parameter is optional its default value will be
+    displayed. For example the <link
+    linkend="function-gobject--signal-lookup"><function>gobject.signal_lookup</function>()</link>
+    function synopsis is:</para>
+
+    <programlisting>
+<methodsynopsis language="python">
+	<methodname><link
+linkend="function-gobject--signal-lookup">gobject.signal_lookup</link></methodname>
+	<methodparam><parameter
+		       role="keyword">name</parameter></methodparam>
+	<methodparam><parameter
+		       role="keyword">type</parameter></methodparam>
+      </methodsynopsis>
+</programlisting>
+
+    <para>The parameters <parameter>name</parameter> and
+    <parameter>type</parameter> are keyword parameters that can be specified
+    in a call either by position or keyword (in which case position is not
+    important). The following calls have the same result:</para>
+
+    <programlisting>
+  id = gobject.signal_lookup("clicked", gtk.Button)
+  id = gobject.signal_lookup("clicked", type=gtk.Button)
+  id = gobject.signal_lookup(name="clicked", type=gtk.Button)
+  id = gobject.signal_lookup(type=gtk.Button, name="clicked")
+</programlisting>
+
+    <para>Parameters that are not keyword parameters are displayed in
+<emphasis>italic</emphasis> and must be specified positionally but may also
+be optional.</para>
+
+  </sect1>
+
+  <sect1 id="pygobject-reference-copyright">
+    <title>Copyright and License Notice</title>
+
+    <para>The PyGObject 2.0 Reference is Copyright (C) 2004-2006 John
+    Finlay.</para>
+
+    <para>This work is licensed under the Creative Commons
+    Attribution-ShareAlike License. To view a copy of this license, visit
+    <ulink
+    url="http://creativecommons.org/licenses/by-sa/1.0/">http://creativecommons.org/licenses/by-sa/1.0/</ulink>
+    or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford,
+    California 94305, USA.</para>
+
+  </sect1>
+
+  </chapter>