docs: fix up reference docs a bit

      - require GTK-Doc 1.19
      - remove sgml mode
      - automatically generate gi.types (needs GTK-Doc 1.19)
      - fix https://bugzilla.gnome.org/show_bug.cgi?id=700025
[WIP] - rearange sections a bit
[WIP] - add gi-building, gi-programming sections
[WIP] - mark missing docs with TODO, which is only marginaly
        better than nothing but at least can be grepped :)

https://bugzilla.gnome.org/show_bug.cgi?id=571648

12 files changed, 830 insertions, 487 deletions

diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
index 937ac808..d3b3f930 100644
--- a/docs/reference/Makefile.am
+++ b/docs/reference/Makefile.am
@@ -1,61 +1,121 @@
 AUTOMAKE_OPTIONS = 1.6
 
-# The name of the module.
+# The name of the module, e.g. 'glib'.
 DOC_MODULE=gi
 
-# The top-level SGML file.
-DOC_MAIN_SGML_FILE=gi-docs.sgml
+# Uncomment for versioned docs and specify the version of the module, e.g. '2'.
+#DOC_MODULE_VERSION=2
 
-# The directory containing the source code. Relative to $(srcdir)
+# The top-level XML file (SGML in the past). You can change this if you want to.
+DOC_MAIN_SGML_FILE=gi-docs.xml
+
+# Directories containing the source code.
+# gtk-doc will search all .c and .h files beneath these paths
+# for inline comments documenting functions and macros.
+# e.g. DOC_SOURCE_DIR=$(top_srcdir)/gtk $(top_srcdir)/gdk
 DOC_SOURCE_DIR=$(top_srcdir)/girepository
 
-# Extra options to supply to gtkdoc-scan
-SCAN_OPTIONS=
+# Extra options to pass to gtkdoc-scangobj. Not normally needed.
+SCANGOBJ_OPTIONS=
 
-# Extra options to supply to gtkdoc-mkdb
-MKDB_OPTIONS=--sgml-mode --output-format=xml --name-space=g --ignore-files=cmph
+# Extra options to supply to gtkdoc-scan.
+# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED"
+SCAN_OPTIONS=--rebuild-types
 
-# Used for dependencies
-HFILE_GLOB=$(top_srcdir)/girepository/*.h
-CFILE_GLOB=$(top_srcdir)/girepository/*.c
+# Extra options to supply to gtkdoc-mkdb.
+# e.g. MKDB_OPTIONS=--xml-mode --output-format=xml
+MKDB_OPTIONS=--xml-mode --output-format=xml --name-space=g --ignore-files=cmph
 
-# Headers to ignore
-IGNORE_HFILES= \
-    girnode.h	    \
-    ginfo.h	    \
-    girparser.h	    \
-    girwriter.h	    \
-    girmodule.h
+# Extra options to supply to gtkdoc-mktmpl
+# e.g. MKTMPL_OPTIONS=--only-section-tmpl
+MKTMPL_OPTIONS=
 
-AM_CPPFLAGS=$(GIREPO_CFLAGS) -I$(top_srcdir)
-GTKDOC_LIBS = $(GIREPO_LIBS) $(top_builddir)/libgirepository-1.0.la $(top_builddir)/libgirepository-internals.la
+# Extra options to supply to gtkdoc-mkhtml
+MKHTML_OPTIONS=
 
-content_files = \
-    gi-gir-reference.xml    \
-    gi-gir.sgml		    \
-    gi-overview.xml	    \
-    gi-struct-hierarchy.xml
+# Extra options to supply to gtkdoc-fixref. Not normally needed.
+# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html
+FIXXREF_OPTIONS=
+
+# Used for dependencies. The docs will be rebuilt if any of these change.
+# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h
+# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c
+HFILE_GLOB=$(top_srcdir)/girepository/*.h
+CFILE_GLOB=$(top_srcdir)/girepository/*.c
 
-HTML_IMAGES = \
+# Extra header to include when scanning, which are not under DOC_SOURCE_DIR
+# e.g. EXTRA_HFILES=$(top_srcdir}/contrib/extra.h
+EXTRA_HFILES=
+
+# Header files or dirs to ignore when scanning. Use base file/dir names
+# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h private_code
+IGNORE_HFILES=						\
+	cmph						\
+	girnode.h					\
+	girparser.h					\
+	girwriter.h					\
+	girmodule.h					\
+	girepository-private.h
+
+# Images to copy into HTML directory.
+# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
+HTML_IMAGES=						\
     $(srcdir)/images/overview.png
 
-# Extra options to supply to gtkdoc-fixref
-FIXXREF_OPTIONS=
+# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
+# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
+content_files=						\
+	overview-building.xml				\
+	overview-programming.xml			\
+	gi-gir-reference.xml				\
+	gi-struct-hierarchy.xml				\
+	version.xml
+
+# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
+# These files must be listed here *and* in content_files
+# e.g. expand_content_files=running.sgml
+#
+# Set to $(content_files) for simplicity, so we can always
+# simply <xi:include href="xml/whatever.xml"/>, even for manually
+# written .xml files...
+expand_content_files=$(content_files)
+
+# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
+# Only needed if you are using gtkdoc-scangobj to dynamically query widget
+# signals and properties.
+# e.g. GTKDOC_CFLAGS=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
+# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
+GTKDOC_CFLAGS=						\
+	-I$(top_srcdir)					\
+	$(GIREPO_CFLAGS)
+
+GTKDOC_LIBS=						\
+	$(top_builddir)/libgirepository-1.0.la		\
+	$(top_builddir)/libgirepository-internals.la	\
+	$(GIREPO_LIBS)
 
-# include common portion ...
+# Other files to distribute
+# e.g. EXTRA_DIST += version.xml.in
 include $(top_srcdir)/gtk-doc.make
+
 # Other files to distribute
 EXTRA_DIST += version.xml.in
 
-gtk-docs-clean:
-	rm -fr html tmpl xml
-
-clean-local: gtk-docs-clean
-
-########################################################################
-
-dist-hook-local: $(BUILT_EXTRA_DIST)
-	files='$(BUILT_EXTRA_DIST)';				\
-	for f in $$files; do					\
-	  if test -f $$f; then d=.; else d=$(srcdir); fi;	\
-	  cp $$d/$$f $(distdir) || exit 1; done
+# Files not to distribute
+# for --rebuild-types in $(SCAN_OPTIONS), e.g. $(DOC_MODULE).types
+# for --rebuild-sections in $(SCAN_OPTIONS) e.g. $(DOC_MODULE)-sections.txt
+#DISTCLEANFILES +=
+
+if ENABLE_GTK_DOC
+TESTS_ENVIRONMENT = \
+  DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
+  SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir)
+# Comment this out if you want 'make check' to test you doc status
+# and run some sanity checks
+## Note: Uncoment this when we start depending on GTK-Doc 1.20
+## which solves https://bugzilla.gnome.org/show_bug.cgi?id=701638
+##TESTS = $(GTKDOC_CHECK)
+endif
+
+gi-docs-clean: clean
+	cd $(srcdir) && rm -rf xml html
diff --git a/docs/reference/gi-docs.sgml b/docs/reference/gi-docs.sgml
deleted file mode 100644
index 2f8bf861..00000000
--- a/docs/reference/gi-docs.sgml
+++ /dev/null
@@ -1,83 +0,0 @@
-<?xml version="1.0" encoding="utf-8" ?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
-<!ENTITY version SYSTEM "version.xml">
-]>
-<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
-  <bookinfo>
-    <title>GObject Introspection Reference Manual</title>
-  </bookinfo>
-
-  <chapter id="glib">
-    <title>GObject-Introspection Overview</title>
-    <para>
-Bla bla bla bla bla
-    </para>
-      <xi:include href="gi-overview.xml"/>
-<!--
-    &gi-building;
--->
-  </chapter>
-
-<!--
-  <chapter id="tools">
-    <title>GObject Introspection Tools</title>
-
-    &g-ir-scanner;
-    &g-ir-compiler;
-    &g-ir-generator;
-  </chapter>
--->
-
-  <part id="girepository">
-    <chapter id="gi-libgirepository">
-      <title>GIRepository</title>
-      <xi:include href="xml/girepository.xml"/>
-    </chapter>
-    <chapter id="gi-ffi">
-      <title>GIR Foreign functions interface</title>
-      <xi:include href="xml/girffi.xml"/>
-    </chapter>
-    <chapter id="gi-repository-structs">
-      <title>GIRepository structs</title>
-      <xi:include href="gi-struct-hierarchy.xml"/>
-      <xi:include href="xml/gibaseinfo.xml"/>
-      <xi:include href="xml/gifunctioninfo.xml"/>
-      <xi:include href="xml/gicallableinfo.xml"/>
-      <xi:include href="xml/giarginfo.xml"/>
-      <xi:include href="xml/gitypeinfo.xml"/>
-      <xi:include href="xml/gistructinfo.xml"/>
-      <xi:include href="xml/giunioninfo.xml"/>
-      <xi:include href="xml/gifieldinfo.xml"/>
-      <xi:include href="xml/gipropertyinfo.xml"/>
-      <xi:include href="xml/givfuncinfo.xml"/>
-      <xi:include href="xml/gisignalinfo.xml"/>
-      <xi:include href="xml/gienuminfo.xml"/>
-      <xi:include href="xml/giregisteredtypeinfo.xml"/>
-      <xi:include href="xml/giobjectinfo.xml"/>
-      <xi:include href="xml/giinterfaceinfo.xml"/>
-      <xi:include href="xml/giconstantinfo.xml"/>
-      <xi:include href="xml/gierrordomaininfo.xml"/>
-    </chapter>
-
-  </part>
-
-
-  <part id="gi-gir">
-    <title>GIR markup format</title>
-      <xi:include href="gi-gir-reference.xml" />
-<!--
-    &gi-gir-creating;
-    &gi-gir-parsing;
-    &gi-gir-verifying;
--->
-  </part>
-
-  <chapter id="gi-typelib">
-    <title>Typelib binary format</title>
-    <xi:include href="xml/gtypelib.xml" />
-  </chapter>
-
-   <xi:include href="xml/annotation-glossary.xml" />
-</book>
diff --git a/docs/reference/gi-docs.xml b/docs/reference/gi-docs.xml
new file mode 100644
index 00000000..b6bc54f1
--- /dev/null
+++ b/docs/reference/gi-docs.xml
@@ -0,0 +1,174 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+<!ENTITY version SYSTEM "xml/version.xml">
+]>
+<book id="index" lang="en" xmlns:xi="http://www.w3.org/2003/XInclude">
+  <title>GObject Introspection Reference Manual</title>
+  <bookinfo>
+    <title>GObject Introspection Reference Manual</title>
+    <releaseinfo>
+      This document is for GObject Introspection version &version;.
+      The latest version of this documentation can be found on-line at
+      <ulink type="http" url="http://developer.gnome.org/gi/unstable/">http://developer.gnome.org/gi/unstable/</ulink>.
+    </releaseinfo>
+  </bookinfo>
+
+  <part id="overview">
+    <title>GObject-Introspection Overview</title>
+    <para>
+      GObject-Introspection is striving to provide a middleware layer between
+      (GObject based) C libraries and language bindings. The primary goal of
+      this project is to minimize duplicated effort in language binding
+      projects by providing shared metadata files on bound C libraries.
+      Language bindings can read these metadata files at runtime to learn
+      how to interface with a bound C library.
+    </para>
+
+    <xi:include href="xml/overview-building.xml"/>
+    <xi:include href="xml/overview-programming.xml"/>
+    <!-- <chapter>
+      <title>Introduction</title>
+
+      <para>
+        Metadata provided by GObject-Introspection is represented by a
+        number of structures:
+        <synopsis>
+        * <link linkend="gi-GIBaseInfo">GIBaseInfo</link>
+          * <link linkend="gi-GICallableInfo">GICallableInfo</link>
+            * <link linkend="gi-GIFunctionInfo">GIFunctionInfo</link>
+            * <link linkend="gi-GISignalInfo">GISignalInfo</link>
+            * <link linkend="gi-GIVFuncInfo">GIVFuncInfo</link>
+          * <link linkend="gi-GIRegisteredTypeInfo">GIRegisteredTypeInfo</link>
+            * <link linkend="gi-GIEnumInfo">GIEnumInfo</link>
+            * <link linkend="gi-GIInterfaceInfo">GIInterfaceInfo</link>
+            * <link linkend="gi-GIObjectInfo">GIObjectInfo</link>
+            * <link linkend="gi-GIStructInfo">GIStructInfo</link>
+            * <link linkend="gi-GIUnionInfo">GIUnionInfo</link>
+          * <link linkend="gi-GIArgInfo">GIArgInfo</link>
+          * <link linkend="gi-GIConstantInfo">GIConstantInfo</link>
+          * <link linkend="gi-GIFieldInfo">GIFieldInfo</link>
+          * <link linkend="gi-GIPropertyInfo">GIPropertyInfo</link>
+          * <link linkend="gi-GITypeInfo">GITypeInfo</link>
+        </synopsis>
+      </para>
+    </chapter> -->
+
+<!--
+    <chapter id="tools">
+      <title>GObject Introspection Tools</title>
+
+      &g-ir-scanner;
+      &g-ir-compiler;
+      &g-ir-generator;
+    </chapter>
+-->
+
+    <para>
+      The GObject-Introspection package contains of a few different parts:
+      <itemizedlist>
+        <listitem>
+          <para>The GIR XML format - an XML format describing the exported C API including documentation</para>
+        </listitem>
+        <listitem>
+          <para>The GTypelib format - a binary format optimized for fast disk access and low memory usage</para>
+        </listitem>
+        <listitem>
+          <para>g-ir-scanner - parses C source code and gtk-doc comments and generates GIR XML files</para>
+        </listitem>
+        <listitem>
+          <para>g-ir-compiler - compiles GIR XML files into typelibs</para>
+        </listitem>
+        <listitem>
+          <para>libgirepository - library to access typelib from C</para>
+        </listitem>
+      </itemizedlist>
+    </para>
+    <para>The following illustration shows how the different components fit together:</para>
+    <inlinegraphic fileref="overview.png" format="PNG"></inlinegraphic>
+  </part>
+
+  <part id="gi">
+    <title>API Reference</title>
+    <chapter>
+      <title>GIRepository</title>
+      <xi:include href="xml/girepository.xml"/>
+      <xi:include href="xml/gi-struct-hierarchy.xml"/>
+
+      <xi:include href="xml/gicommontypes.xml"/>
+
+      <xi:include href="xml/gibaseinfo.xml"/>
+
+      <xi:include href="xml/gicallableinfo.xml"/>
+        <xi:include href="xml/gifunctioninfo.xml"/>
+        <xi:include href="xml/gicallbackinfo.xml"/>
+        <xi:include href="xml/gisignalinfo.xml"/>
+        <xi:include href="xml/givfuncinfo.xml"/>
+
+      <xi:include href="xml/giregisteredtypeinfo.xml"/>
+        <xi:include href="xml/gienuminfo.xml"/>
+        <xi:include href="xml/gistructinfo.xml"/>
+        <xi:include href="xml/giunioninfo.xml"/>
+        <xi:include href="xml/giobjectinfo.xml"/>
+        <xi:include href="xml/giinterfaceinfo.xml"/>
+
+      <xi:include href="xml/giarginfo.xml"/>
+      <xi:include href="xml/giconstantinfo.xml"/>
+      <xi:include href="xml/gifieldinfo.xml"/>
+      <xi:include href="xml/gipropertyinfo.xml"/>
+      <xi:include href="xml/gitypeinfo.xml"/>
+      <xi:include href="xml/givalueinfo.xml"/>
+    </chapter>
+
+    <chapter id="gi-typelib">
+      <title>GITypelib</title>
+      <xi:include href="xml/gitypelib.xml" />
+      <xi:include href="xml/gitypelib-internal.xml"/>
+    </chapter>
+
+    <chapter>
+      <title>TODO</title>
+      <xi:include href="xml/girffi.xml"/>
+
+      <xi:include href="xml/gi-gir-reference.xml"/>
+      <!--
+      &gi-gir-creating;
+      &gi-gir-parsing;
+      &gi-gir-verifying;
+       -->
+    </chapter>
+
+  </part>
+
+  <index id="api-index-full">
+    <title id="index-all">Index</title>
+    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-deprecated" role="deprecated">
+    <title>Index of deprecated symbols</title>
+    <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-1-29-0" role="1.29.0">
+    <title>Index of new symbols in 1.29.0</title>
+    <xi:include href="xml/api-index-1.29.0.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-1-29-17" role="1.29.17">
+    <title>Index of new symbols in 1.29.17</title>
+    <xi:include href="xml/api-index-1.29.17.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-1-30-1" role="1.30.1">
+    <title>Index of new symbols in 1.30.1</title>
+    <xi:include href="xml/api-index-1.30.1.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-1-34" role="1.34">
+    <title>Index of new symbols in 1.34</title>
+    <xi:include href="xml/api-index-1.34.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-1-35-8" role="1.35.8">
+    <title>Index of new symbols in 1.35.8</title>
+    <xi:include href="xml/api-index-1.35.8.xml"><xi:fallback /></xi:include>
+  </index>
+
+  <xi:include href="xml/annotation-glossary.xml" />
+</book>
diff --git a/docs/reference/gi-gir-reference.xml b/docs/reference/gi-gir-reference.xml
index 8d19112e..fb97984f 100644
--- a/docs/reference/gi-gir-reference.xml
+++ b/docs/reference/gi-gir-reference.xml
@@ -1,114 +1,121 @@
-<chapter id="gi-gir-reference">
-
-  <title>The GIR XML format</title>
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+<!ENTITY version SYSTEM "version.xml">
+]>
+<refentry id="gi-gir-reference">
+	<refmeta>
+	  <refentrytitle role="top_of_page" id="gi-gir-reference.top_of_page">The GIR XML format</refentrytitle>
+	  <manvolnum>3</manvolnum>
+	  <refmiscinfo>The GIR XML format</refmiscinfo>
+	</refmeta>
+	<refnamediv>
+	  <refname>The GIR XML format</refname>
+	  <refpurpose>The GIR XML format</refpurpose>
+	</refnamediv>
 
   <para>
     This chapter describes the GIR XML markup format.
   </para>
 
-   <refsect2 id="gi-gir-api">
-     <title><emphasis>api</emphasis> node</title>
-
-     The root node of all GIR documents is the api node.
-
-     Possible children: <link linkend="gi-gir-namespace">namespace</link>.
-
-     <example>
-     <title>A GIR fragment showing an api node</title>
-     <programlisting><![CDATA[
-     <api version="1.0">
-       <namespace/>
-     </api>]]></programlisting>
-     </example>
-
-   </refsect2>
-
-   <refsect2 id="gi-gir-namespace">
-     <title><emphasis>namespace</emphasis> node</title>
-
-     Parent node: <link linkend="gi-gir-api">api</link>.
-     Possible children: <link linkend="gi-gir-callback">callback</link>,
-     <link linkend="gi-gir-class">class</link>,
-     <link linkend="gi-gir-function">function</link>.
-     <link linkend="gi-gir-interface">interface</link>.
-
-     <example>
-     <title>A GIR fragment showing an namespace node</title>
-     <programlisting><![CDATA[
-     <api version="1.0">
-       <namespace="Gtk">
-          <class/>
-          <function/>
-       </namespace>
-     </api>]]></programlisting>
-     </example>
-
+  <refsect2 id="gi-gir-api-node">
+    <title><emphasis>api</emphasis> node</title>
+
+    The root node of all GIR documents is the api node.
+
+    Possible children: <link linkend="gi-gir-namespace">namespace</link>.
+
+    <example>
+    <title>A GIR fragment showing an api node</title>
+    <programlisting><![CDATA[
+    <api version="1.0">
+      <namespace/>
+    </api>]]></programlisting>
+    </example>
+  </refsect2>
+
+  <refsect2 id="gi-gir-namespace">
+    <title><emphasis>namespace</emphasis> node</title>
+
+    Parent node: <link linkend="gi-gir-api">api</link>.
+    Possible children: <link linkend="gi-gir-callback">callback</link>,
+    <link linkend="gi-gir-class">class</link>,
+    <link linkend="gi-gir-function">function</link>.
+    <link linkend="gi-gir-interface">interface</link>.
+
+    <example>
+    <title>A GIR fragment showing an namespace node</title>
+    <programlisting><![CDATA[
+    <api version="1.0">
+      <namespace="Gtk">
+         <class/>
+         <function/>
+      </namespace>
+    </api>]]></programlisting>
+    </example>
+  </refsect2>
+
+  <refsect2 id="gi-gir-class">
+    <title><emphasis>class</emphasis> node</title>
+
+    Parent node: <link linkend="gi-gir-namespace">namespace</link>.
+    Possible children: <link linkend="gi-gir-class">constructor</link>,
+    <link linkend="gi-gir-field">field</link>,
+    <link linkend="gi-gir-method">method</link>,
+    <link linkend="gi-gir-property">property</link>.
+    <example>
+    <title>A GIR fragment showing an class node</title>
+    <programlisting><![CDATA[
+    <api version="1.0">
+      <namespace="Gtk">
+        <class name="Widget">
+           <constructor/>
+           <field/>
+           <method/>
+           <property/>
+        <class>
+      </namespace>
+    </api>]]></programlisting>
+    </example>
+  </refsect2>
+
+  <refsect2 id="gi-gir-interface">
+    <title><emphasis>interface</emphasis> node</title>
+
+    Parent node: <link linkend="gi-gir-namespace">namespace</link>.
+    Possible children: <link linkend="gi-gir-field">field</link>,
+    <link linkend="gi-gir-method">method</link>,
+    <link linkend="gi-gir-property">property</link>.
+    <example>
+    <title>A GIR fragment showing an interface node</title>
+    <programlisting><![CDATA[
+    <api version="1.0">
+      <namespace="Gtk">
+        <interface name="Buildable">
+           <field/>
+           <method/>
+           <property/>
+        <interface>
+      </namespace>
+    </api>]]></programlisting>
+    </example>
+  </refsect2>
+
+  <refsect2 id="gi-gir-function">
+    <title><emphasis>function</emphasis> node</title>
+
+    Parent node: <link linkend="gi-gir-namespace">namespace</link>.
+    <example>
+    <title>A GIR fragment showing an function node</title>
+    <programlisting><![CDATA[
+    <api version="1.0">
+      <namespace="Gtk">
+        <function name="init">
+        </function>
+      </namespace>
+    </api>]]></programlisting>
+    </example>
    </refsect2>
 
-   <refsect2 id="gi-gir-class">
-     <title><emphasis>class</emphasis> node</title>
-
-     Parent node: <link linkend="gi-gir-namespace">namespace</link>.
-     Possible children: <link linkend="gi-gir-class">constructor</link>,
-     <link linkend="gi-gir-field">field</link>,
-     <link linkend="gi-gir-method">method</link>,
-     <link linkend="gi-gir-property">property</link>.
-     <example>
-     <title>A GIR fragment showing an class node</title>
-     <programlisting><![CDATA[
-     <api version="1.0">
-       <namespace="Gtk">
-         <class name="Widget">
-            <constructor/>
-            <field/>
-            <method/>
-            <property/>
-         <class>
-       </namespace>
-     </api>]]></programlisting>
-     </example>
-
-   </refsect2>
-
-   <refsect2 id="gi-gir-interface">
-     <title><emphasis>interface</emphasis> node</title>
-
-     Parent node: <link linkend="gi-gir-namespace">namespace</link>.
-     Possible children: <link linkend="gi-gir-field">field</link>,
-     <link linkend="gi-gir-method">method</link>,
-     <link linkend="gi-gir-property">property</link>.
-     <example>
-     <title>A GIR fragment showing an interface node</title>
-     <programlisting><![CDATA[
-     <api version="1.0">
-       <namespace="Gtk">
-         <interface name="Buildable">
-            <field/>
-            <method/>
-            <property/>
-         <interface>
-       </namespace>
-     </api>]]></programlisting>
-     </example>
-
-   </refsect2>
-
-   <refsect2 id="gi-gir-function">
-     <title><emphasis>function</emphasis> node</title>
-
-     Parent node: <link linkend="gi-gir-namespace">namespace</link>.
-     <example>
-     <title>A GIR fragment showing an function node</title>
-     <programlisting><![CDATA[
-     <api version="1.0">
-       <namespace="Gtk">
-         <function name="init">
-         </function>
-       </namespace>
-     </api>]]></programlisting>
-     </example>
-
-   </refsect2>
-
-</chapter>
-
+</refentry>
diff --git a/docs/reference/gi-gir.sgml b/docs/reference/gi-gir.sgml
deleted file mode 100644
index 590444ff..00000000
--- a/docs/reference/gi-gir.sgml
+++ /dev/null
@@ -1,23 +0,0 @@
-<chapter id="gi-gir-reference">
-
-  <title>The GIR XML format</title>
-
-  <para>
-    This chapter describes the GIR XML markup format.
-  </para>
-
-   <section id="gi-gir-api">
-      <title>API node</title>
-      
-      The root node of all GIR documents is the api node.
-
-      Attributes:
-      <itemizedlist>
-	<listitem><para>version</para></listitem>
-        The version of the GIR, currently the only known version is 1.0.
-      </itemizedlist>
-
-   </section>
-
-</chapter>
-
diff --git a/docs/reference/gi-overview.xml b/docs/reference/gi-overview.xml
deleted file mode 100644
index 0943b8e5..00000000
--- a/docs/reference/gi-overview.xml
+++ /dev/null
@@ -1,52 +0,0 @@
-<?xml version="1.0" encoding="utf-8" ?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
-<!ENTITY version SYSTEM "version.xml">
-]>
-<refentry id="gi-overview">
-<refmeta>
-  <refentrytitle role="top_of_page" id="gi-overview.top_of_page">Introspection Overview</refentrytitle>
-  <manvolnum>3</manvolnum>
-  <refmiscinfo>GI Library</refmiscinfo>
-</refmeta>
-<refnamediv>
-  <refname>Overview</refname>
-  <refpurpose>General overview of introspection</refpurpose>
-</refnamediv>
-
-<refsynopsisdiv>
-The GObject-Introspection package contains of a few different parts:
-  <itemizedlist>
-    <listitem>
-      <para>The GIR XML format - an XML format describing the exported
-      C API including documentation
-      </para>
-    </listitem>
-    <listitem>
-      <para>The GTypelib format - a binary format optimized for fast disk access
-      and low memory usage
-      </para>
-    </listitem>
-    <listitem>
-      <para>g-ir-scanner - parses C source code and gtk-doc comments and
-      generates GIR XML files
-      </para>
-    </listitem>
-    <listitem>
-      <para>g-ir-compiler - compiles GIR XML files into typelibs
-      </para>
-    </listitem>
-    <listitem>
-      <para>libgirepository - library to access typelib from C
-      </para>
-    </listitem>
-  </itemizedlist>
-
-<para>A quick overview how the different components fits together:</para>
-
-<inlinegraphic fileref="overview.png" format="PNG"></inlinegraphic>
-
-</refsynopsisdiv>
-
-</refentry>
diff --git a/docs/reference/gi-sections.txt b/docs/reference/gi-sections.txt
index 8b880cf8..59f0d50a 100644
--- a/docs/reference/gi-sections.txt
+++ b/docs/reference/gi-sections.txt
@@ -1,126 +1,180 @@
 <SECTION>
 <FILE>girepository</FILE>
-GICallbackInfo
+<TITLE>GIRepository</TITLE>
 GIRepository
-GIRepositoryError
 GIRepositoryLoadFlags
-GITypelib
 g_irepository_get_default
-g_irepository_prepend_search_path
+g_irepository_get_dependencies
+g_irepository_get_loaded_namespaces
+g_irepository_get_n_infos
+g_irepository_get_info
+g_irepository_get_option_group
+g_irepository_enumerate_versions
+<SUBSECTION>
 g_irepository_prepend_library_path
+g_irepository_prepend_search_path
 g_irepository_get_search_path
+<SUBSECTION>
 g_irepository_load_typelib
+g_irepository_get_typelib_path
 g_irepository_is_registered
-g_irepository_find_by_name
 g_irepository_require
 g_irepository_require_private
-g_irepository_get_dependencies
-g_irepository_get_loaded_namespaces
-g_irepository_find_by_gtype
-g_irepository_get_n_infos
-g_irepository_get_info
-g_irepository_get_typelib_path
+g_irepository_get_c_prefix
 g_irepository_get_shared_library
 g_irepository_get_version
-g_irepository_get_option_group
-g_irepository_get_c_prefix
+<SUBSECTION>
+g_irepository_find_by_gtype
+g_irepository_find_by_error_domain
+g_irepository_find_by_name
+<SUBSECTION>
 g_irepository_dump
-g_irepository_enumerate_versions
+<SUBSECTION>
+gi_cclosure_marshal_generic
+<SUBSECTION>
 G_IREPOSITORY_ERROR
-g_typelib_new_from_memory
-g_typelib_new_from_const_memory
-g_typelib_new_from_mapped_file
-g_typelib_free
-g_typelib_symbol
-g_typelib_get_namespace
+GIRepositoryError
 <SUBSECTION Standard>
 GIRepositoryClass
 G_TYPE_IREPOSITORY
 G_IREPOSITORY
 G_IREPOSITORY_CLASS
-G_IREPOSITORY_GET_CLASS
 G_IS_IREPOSITORY
 G_IS_IREPOSITORY_CLASS
+G_IREPOSITORY_GET_CLASS
 <SUBSECTION Private>
-g_info_new
 GIRepositoryPrivate
 g_irepository_get_type
 g_irepository_error_quark
-GIRealInfo
-GIUnresolvedInfo
 </SECTION>
 
 <SECTION>
 <FILE>gibaseinfo</FILE>
 GIInfoType
-g_info_type_to_string
 GIAttributeIter
-GIBaseInfo
+g_info_new
 g_base_info_ref
 g_base_info_unref
+g_base_info_equal
 g_base_info_get_type
-g_base_info_get_name
+g_base_info_get_typelib
 g_base_info_get_namespace
-g_base_info_is_deprecated
+g_base_info_get_name
 g_base_info_get_attribute
 g_base_info_iterate_attributes
 g_base_info_get_container
-g_base_info_get_typelib
-g_base_info_equal
+g_base_info_is_deprecated
+<SUBSECTION Standard>
+GI_TYPE_BASE_INFO
+g_base_info_gtype_get_type
 <SUBSECTION Private>
 GIBaseInfoStub
 </SECTION>
 
 <SECTION>
+<FILE>giarginfo</FILE>
+GI_IS_ARG_INFO
+GIArgInfo
+GIDirection
+GIScopeType
+GITransfer
+g_arg_info_get_closure
+g_arg_info_get_destroy
+g_arg_info_get_direction
+g_arg_info_get_ownership_transfer
+g_arg_info_get_scope
+g_arg_info_get_type
+g_arg_info_load_type
+g_arg_info_may_be_null
+g_arg_info_is_caller_allocates
+g_arg_info_is_optional
+g_arg_info_is_return_value
+g_arg_info_is_skip
+</SECTION>
+
+<SECTION>
 <FILE>gicallableinfo</FILE>
 GI_IS_CALLABLE_INFO
 GICallableInfo
-g_callable_info_get_return_type
+g_callable_info_can_throw_gerror
+g_callable_info_get_n_args
+g_callable_info_get_arg
 g_callable_info_get_caller_owns
-g_callable_info_may_return_null
 g_callable_info_get_return_attribute
+g_callable_info_get_return_type
+g_callable_info_invoke
+g_callable_info_is_method
 g_callable_info_iterate_return_attributes
-g_callable_info_get_n_args
-g_callable_info_get_arg
 g_callable_info_load_arg
 g_callable_info_load_return_type
+g_callable_info_may_return_null
+g_callable_info_skip_return
+</SECTION>
+
+<SECTION>
+<FILE>gicommontypes</FILE>
+GIArgument
+GIUnresolvedInfo
+GITypeTag
+GIArrayType
+GI_TYPE_TAG_N_TYPES
+G_TYPE_TAG_IS_BASIC
+</SECTION>
+
+<SECTION>
+<FILE>gicallbackinfo</FILE>
+GICallbackInfo
 </SECTION>
 
 <SECTION>
 <FILE>giconstantinfo</FILE>
 GI_IS_CONSTANT_INFO
 GIConstantInfo
+g_constant_info_free_value
 g_constant_info_get_type
 g_constant_info_get_value
 </SECTION>
 
 <SECTION>
-<FILE>givfuncinfo</FILE>
-GI_IS_VFUNC_INFO
-GIVFuncInfo
-GIVFuncInfoFlags
-g_vfunc_info_get_flags
-g_vfunc_info_get_offset
-g_vfunc_info_get_signal
-g_vfunc_info_get_invoker
+<FILE>gienuminfo</FILE>
+GI_IS_ENUM_INFO
+GI_IS_VALUE_INFO
+GIEnumInfo
+g_enum_info_get_n_values
+g_enum_info_get_value
+g_enum_info_get_n_methods
+g_enum_info_get_method
+g_enum_info_get_storage_type
+g_enum_info_get_error_domain
+g_value_info_get_value
 </SECTION>
 
 <SECTION>
-<FILE>gisignalinfo</FILE>
-GI_IS_SIGNAL_INFO
-GISignalInfo
-g_signal_info_get_flags
-g_signal_info_get_class_closure
-g_signal_info_true_stops_emit
+<FILE>gifieldinfo</FILE>
+GI_IS_FIELD_INFO
+GIFieldInfo
+GIFieldInfoFlags
+g_field_info_get_field
+g_field_info_set_field
+g_field_info_get_flags
+g_field_info_get_offset
+g_field_info_get_size
+g_field_info_get_type
 </SECTION>
 
 <SECTION>
-<FILE>gipropertyinfo</FILE>
-GI_IS_PROPERTY_INFO
-GIPropertyInfo
-g_property_info_get_flags
-g_property_info_get_type
-g_property_info_get_ownership_transfer
+<FILE>gifunctioninfo</FILE>
+GI_IS_FUNCTION_INFO
+GIFunctionInfo
+GIFunctionInfoFlags
+g_function_info_get_flags
+g_function_info_get_property
+g_function_info_get_symbol
+g_function_info_get_vfunc
+g_function_info_invoke
+G_INVOKE_ERROR
+g_invoke_error_quark
+GInvokeError
 </SECTION>
 
 <SECTION>
@@ -139,64 +193,70 @@ g_interface_info_get_signal
 g_interface_info_find_signal
 g_interface_info_get_n_vfuncs
 g_interface_info_get_vfunc
+g_interface_info_find_vfunc
 g_interface_info_get_n_constants
 g_interface_info_get_constant
 g_interface_info_get_iface_struct
-g_interface_info_find_vfunc
 </SECTION>
 
 <SECTION>
 <FILE>giobjectinfo</FILE>
 GI_IS_OBJECT_INFO
 GIObjectInfo
-GIObjectInfoGetValueFunction
-GIObjectInfoRefFunction
-GIObjectInfoSetValueFunction
-GIObjectInfoUnrefFunction
-g_object_info_get_type_name
-g_object_info_get_type_init
 g_object_info_get_abstract
 g_object_info_get_fundamental
 g_object_info_get_parent
-g_object_info_get_n_interfaces
-g_object_info_get_interface
+g_object_info_get_type_name
+g_object_info_get_type_init
+<SUBSECTION>
+g_object_info_get_n_constants
+g_object_info_get_constant
+<SUBSECTION>
 g_object_info_get_n_fields
 g_object_info_get_field
-g_object_info_get_n_properties
-g_object_info_get_property
+<SUBSECTION>
+g_object_info_get_n_interfaces
+g_object_info_get_interface
+<SUBSECTION>
 g_object_info_get_n_methods
 g_object_info_get_method
 g_object_info_find_method
+g_object_info_find_method_using_interfaces
+<SUBSECTION>
+g_object_info_get_n_properties
+g_object_info_get_property
+<SUBSECTION>
 g_object_info_get_n_signals
 g_object_info_get_signal
+g_object_info_find_signal
+<SUBSECTION>
 g_object_info_get_n_vfuncs
 g_object_info_get_vfunc
-g_object_info_get_n_constants
-g_object_info_get_constant
-g_object_info_get_class_struct
 g_object_info_find_vfunc
-g_object_info_get_unref_function
-g_object_info_get_unref_function_pointer
+g_object_info_find_vfunc_using_interfaces
+<SUBSECTION>
+g_object_info_get_class_struct
 g_object_info_get_ref_function
 g_object_info_get_ref_function_pointer
+g_object_info_get_unref_function
+g_object_info_get_unref_function_pointer
 g_object_info_get_set_value_function
 g_object_info_get_set_value_function_pointer
 g_object_info_get_get_value_function
 g_object_info_get_get_value_function_pointer
+GIObjectInfoRefFunction
+GIObjectInfoUnrefFunction
+GIObjectInfoSetValueFunction
+GIObjectInfoGetValueFunction
 </SECTION>
 
 <SECTION>
-<FILE>gienuminfo</FILE>
-GI_IS_ENUM_INFO
-GI_IS_VALUE_INFO
-GIEnumInfo
-GIValueInfo
-g_enum_info_get_n_values
-g_enum_info_get_value
-g_enum_info_get_n_methods
-g_enum_info_get_method
-g_enum_info_get_storage_type
-g_value_info_get_value
+<FILE>gipropertyinfo</FILE>
+GI_IS_PROPERTY_INFO
+GIPropertyInfo
+g_property_info_get_flags
+g_property_info_get_ownership_transfer
+g_property_info_get_type
 </SECTION>
 
 <SECTION>
@@ -209,78 +269,52 @@ g_registered_type_info_get_g_type
 </SECTION>
 
 <SECTION>
+<FILE>girffi</FILE>
+GIFFIClosureCallback
+GIFunctionInvoker
+GIFFIReturnValue
+gi_type_tag_get_ffi_type
+g_type_info_get_ffi_type
+gi_type_info_extract_ffi_return_value
+g_function_info_prep_invoker
+g_function_invoker_new_for_address
+g_function_invoker_destroy
+g_callable_info_prepare_closure
+g_callable_info_free_closure
+</SECTION>
+
+<SECTION>
+<FILE>gisignalinfo</FILE>
+GI_IS_SIGNAL_INFO
+GISignalInfo
+g_signal_info_get_flags
+g_signal_info_get_class_closure
+g_signal_info_true_stops_emit
+</SECTION>
+
+<SECTION>
 <FILE>gistructinfo</FILE>
 GI_IS_STRUCT_INFO
 GIStructInfo
+g_struct_info_get_alignment
+g_struct_info_get_size
+g_struct_info_is_gtype_struct
+g_struct_info_is_foreign
+<SUBSECTION>
 g_struct_info_get_n_fields
 g_struct_info_get_field
+<SUBSECTION>
 g_struct_info_get_n_methods
 g_struct_info_get_method
 g_struct_info_find_method
-g_struct_info_get_size
-g_struct_info_get_alignment
-g_struct_info_is_gtype_struct
-g_struct_info_is_foreign
-</SECTION>
-
-<SECTION>
-<FILE>giunioninfo</FILE>
-GI_IS_UNION_INFO
-GIUnionInfo
-g_union_info_get_n_fields
-g_union_info_get_field
-g_union_info_get_n_methods
-g_union_info_get_method
-g_union_info_is_discriminated
-g_union_info_get_discriminator_offset
-g_union_info_get_discriminator_type
-g_union_info_get_discriminator
-g_union_info_find_method
-g_union_info_get_size
-g_union_info_get_alignment
-</SECTION>
-
-<SECTION>
-<FILE>gifieldinfo</FILE>
-GI_IS_FIELD_INFO
-GIFieldInfo
-GIFieldInfoFlags
-g_field_info_get_flags
-g_field_info_get_size
-g_field_info_get_offset
-g_field_info_get_type
-g_field_info_get_field
-g_field_info_set_field
-</SECTION>
-
-<SECTION>
-<FILE>giarginfo</FILE>
-GI_IS_ARG_INFO
-GIArgInfo
-GIDirection
-GIScopeType
-GITransfer
-g_arg_info_get_direction
-g_arg_info_is_caller_allocates
-g_arg_info_is_return_value
-g_arg_info_is_optional
-g_arg_info_may_be_null
-g_arg_info_get_ownership_transfer
-g_arg_info_get_scope
-g_arg_info_get_closure
-g_arg_info_get_destroy
-g_arg_info_get_type
-g_arg_info_load_type
 </SECTION>
 
 <SECTION>
 <FILE>gitypeinfo</FILE>
 GI_IS_TYPE_INFO
-GIArrayType
 GITypeInfo
-GITypeTag
-G_TYPE_TAG_IS_BASIC
 g_type_tag_to_string
+g_info_type_to_string
 g_type_info_is_pointer
 g_type_info_get_tag
 g_type_info_get_param_type
@@ -288,50 +322,40 @@ g_type_info_get_interface
 g_type_info_get_array_length
 g_type_info_get_array_fixed_size
 g_type_info_is_zero_terminated
-g_type_info_get_n_error_domains
-g_type_info_get_error_domain
 g_type_info_get_array_type
 </SECTION>
 
 <SECTION>
-<FILE>gifunctioninfo</FILE>
-GI_IS_FUNCTION_INFO
-GIFunctionInfo
-GInvokeError
-GIFunctionInfoFlags
-G_INVOKE_ERROR
-g_function_info_get_symbol
-g_function_info_get_flags
-g_function_info_get_property
-g_function_info_get_vfunc
-g_function_info_invoke
-<SUBSECTION Private>
-g_invoke_error_quark
-</SECTION>
-
-<SECTION>
-<FILE>gierrordomaininfo</FILE>
-GI_IS_ERROR_DOMAIN_INFO
-GIErrorDomainInfo
-g_error_domain_info_get_quark
-g_error_domain_info_get_codes
+<FILE>gitypelib</FILE>
+g_typelib_new_from_memory
+g_typelib_new_from_const_memory
+g_typelib_new_from_mapped_file
+g_typelib_free
+g_typelib_symbol
+g_typelib_get_namespace
+GITypelib
 </SECTION>
 
 <SECTION>
-<FILE>gtypelib</FILE>
+<FILE>gitypelib-internal</FILE>
 G_IR_MAGIC
 GTypelibBlobType
 Header
+SectionType
+Section
 DirEntry
+SimpleTypeBlobFlags
+SimpleTypeBlob
 ArgBlob
 SignatureBlob
 CommonBlob
 FunctionBlob
 CallbackBlob
 InterfaceTypeBlob
+ArrayTypeDimension
+ArrayTypeBlob
 ParamTypeBlob
 ErrorTypeBlob
-ErrorDomainBlob
 ValueBlob
 FieldBlob
 RegisteredTypeBlob
@@ -345,27 +369,56 @@ ObjectBlob
 InterfaceBlob
 ConstantBlob
 AttributeBlob
-dimensions
 g_typelib_get_dir_entry
+g_typelib_get_dir_entry_by_name
+g_typelib_get_dir_entry_by_gtype_name
+g_typelib_get_dir_entry_by_error_domain
+g_typelib_matches_gtype_name_prefix
 g_typelib_check_sanity
 g_typelib_get_string
-GTypelibError
+GITypelibError
 G_TYPELIB_ERROR
+g_typelib_error_quark
 g_typelib_validate
+GITypelibHashBuilder
+<SUBSECTION Standard>
 BLOB_IS_REGISTERED_TYPE
-<SUBSECTION Private>
-g_typelib_error_quark
 </SECTION>
 
 <SECTION>
-<FILE>girffi</FILE>
-GIFFIClosureCallback
-GIFunctionInvoker
-gi_cclosure_marshal_generic
-g_type_info_get_ffi_type
-g_function_info_prep_invoker
-g_function_invoker_destroy
-g_callable_info_prepare_closure
-g_callable_info_free_closure
+<FILE>giunioninfo</FILE>
+GIUnionInfo
+g_union_info_get_n_fields
+g_union_info_get_field
+g_union_info_get_n_methods
+g_union_info_get_method
+g_union_info_is_discriminated
+g_union_info_get_discriminator_offset
+g_union_info_get_discriminator_type
+g_union_info_get_discriminator
+g_union_info_find_method
+g_union_info_get_size
+g_union_info_get_alignment
+<SUBSECTION Standard>
+GI_IS_UNION_INFO
+</SECTION>
+
+<SECTION>
+<FILE>givalueinfo</FILE>
+GIValueInfo
+</SECTION>
+
+<SECTION>
+<FILE>givfuncinfo</FILE>
+GIVFuncInfo
+GIVFuncInfoFlags
+g_vfunc_info_get_flags
+g_vfunc_info_get_offset
+g_vfunc_info_get_signal
+g_vfunc_info_get_invoker
+g_vfunc_info_get_address
+g_vfunc_info_invoke
+<SUBSECTION Standard>
+GI_IS_VFUNC_INFO
 </SECTION>
 
diff --git a/docs/reference/gi-struct-hierarchy.xml b/docs/reference/gi-struct-hierarchy.xml
index eea51282..1407485f 100644
--- a/docs/reference/gi-struct-hierarchy.xml
+++ b/docs/reference/gi-struct-hierarchy.xml
@@ -32,7 +32,6 @@
     * <link linkend="gi-GIUnionInfo">GIUnionInfo</link>
   * <link linkend="gi-GIArgInfo">GIArgInfo</link>
   * <link linkend="gi-GIConstantInfo">GIConstantInfo</link>
-  * <link linkend="gi-GIErrorDomainInfo">GIErrorDomainInfo</link>
   * <link linkend="gi-GIFieldInfo">GIFieldInfo</link>
   * <link linkend="gi-GIPropertyInfo">GIPropertyInfo</link>
   * <link linkend="gi-GITypeInfo">GITypeInfo</link>
diff --git a/docs/reference/gi.types b/docs/reference/gi.types
deleted file mode 100644
index 3b4e9df6..00000000
--- a/docs/reference/gi.types
+++ /dev/null
@@ -1,2 +0,0 @@
-g_irepository_get_type
-g_irepository_get_type
diff --git a/docs/reference/overview-building.xml b/docs/reference/overview-building.xml
new file mode 100644
index 00000000..7c843ce3
--- /dev/null
+++ b/docs/reference/overview-building.xml
@@ -0,0 +1,189 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<refentry id="gi-building">
+  <refmeta>
+    <refentrytitle>Compiling the GObject Introspection package</refentrytitle>
+  </refmeta>
+
+  <refnamediv>
+    <refname>Compiling the GObject Introspection Package</refname>
+    <refpurpose>How to compile GObject Introspection itself</refpurpose>
+  </refnamediv>
+
+  <refsect1 id="gi-buildtools">
+    <title>Building on UNIX</title>
+    <para>
+      On UNIX, GObject Introspection uses the standard GNU build system,
+      using <application>autoconf</application> for package
+      configuration and resolving portability issues,
+      <application>automake</application> for building makefiles
+      that comply with the GNU Coding Standards, and
+      <application>libtool</application> for building shared
+      libraries on multiple platforms. The normal sequence for
+      compiling and installing the GObject Introspection package is thus:
+
+      <literallayout>
+        <userinput>./configure</userinput>
+        <userinput>make</userinput>
+        <userinput>make install</userinput>
+      </literallayout>
+    </para>
+
+    <para>
+      The standard options provided by <application>GNU
+      autoconf</application> may be passed to the
+      <command>configure</command> script.  Please see the
+      <application>autoconf</application> documentation or run
+      <command>./configure --help</command> for information about
+      the standard options.
+    </para>
+  </refsect1>
+
+  <refsect1 id="dependencies">
+    <title>Dependencies</title>
+    <para>
+      Before you can compile GObject Introspection, you need to have
+      various other tools and libraries installed on your
+      system. The tools needed during the build process (as
+      differentiated from the basic build tools mentioned
+      <link linkend="gi-buildtools">before</link> are:
+    </para>
+    <itemizedlist>
+      <listitem>
+        <para>
+          <ulink url="http://www.freedesktop.org/software/pkgconfig/">pkg-config</ulink>
+          is a tool for tracking the compilation flags needed for
+          libraries that are used by the GObjecct Introspection. (For each
+          library, a small <literal>.pc</literal> text file is
+          installed in a standard location that contains the compilation
+          flags needed for that library along with version number
+          information.)
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The GObject-Introspection makefiles will mostly work with different
+          versions of <command>make</command>, however, there tends to be a
+          few incompatibilities, so the GObject-Introspection team recommends
+          installing <ulink url="http://www.gnu.org/software/make">GNU
+          make</ulink> if you don't already have it on your system
+          and using it. (It may be called <command>gmake</command>
+          rather than <command>make</command>.)
+        </para>
+      </listitem>
+    </itemizedlist>
+    <para>
+      GObject-Introspection depends on a number of libraries and tools
+      maintained under the umbrella of the GNOME project:
+    </para>
+    <itemizedlist>
+      <listitem>
+        <para>
+          The GLib library provides core non-graphical functionality
+          such as high level data types, Unicode manipulation, and
+          an object and type system to C programs. It is available
+          from the <ulink url="ftp.gnome.org/pub/gnome/sources/glib">GNOME
+          FTP site</ulink> or
+          <ulink url="http://download.gnome.org/sources/glib/">here</ulink>.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          TODO: GTK-Doc
+        </para>
+      </listitem>
+    </itemizedlist>
+    <itemizedlist>
+      <title>External dependencies</title>
+      <listitem>
+        <para>
+          Python
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          GObject Introspection has an option dependency on the
+          <ulink url="TODO">libffi</ulink> library. When available,
+          ...
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+        <para>
+          <ulink url="http://www.cairographics.org">Cairo</ulink>
+          is a graphics library that supports vector graphics and image
+          compositing. When available, GObject Introspection uses
+          Cairo in its unit tests.
+        </para>
+        </para>
+      </listitem>
+    </itemizedlist>
+  </refsect1>
+
+  <refsect1 id="extra-configuration-options">
+    <title>Extra Configuration Options</title>
+
+    <para>
+      In addition to the normal options, the
+      <command>configure</command> script in the GObject Introspection
+      package supports these additional arguments:
+    </para>
+
+    <formalpara>
+      <title><systemitem>--disable-Bsymbolic</systemitem> and
+        <systemitem>--enable-Bsymbolic</systemitem></title>
+
+      <para>
+        By default, the GObject Introspection package uses the
+        -Bsymbolic-functions linker flag to avoid intra-library
+        PLT jumps. A side-effect of this is that it is no longer
+        possible to override internal uses of GObject Introspection
+        functions with <envar>LD_PRELOAD</envar>. Therefore, it may
+        make sense to turn this feature off in some situations.
+        The <option>--disable-Bsymbolic</option> option allows
+        to do that.
+      </para>
+    </formalpara>
+
+    <formalpara>
+      <title><systemitem>--disable-gtk-doc</systemitem> and
+        <systemitem>--enable-gtk-doc</systemitem></title>
+
+      <para>
+        By default the <command>configure</command> script will try
+        to auto-detect whether the
+        <application>gtk-doc</application> package is installed.
+        If it is, then it will use it to extract and build the
+        documentation for the GObject Introspection package. These options
+        can be used to explicitly control whether
+        <application>gtk-doc</application> should be
+        used or not. If it is not used, the distributed,
+        pre-generated HTML files will be installed instead of
+        building them on your machine.
+      </para>
+    </formalpara>
+
+    <formalpara>
+      <title><systemitem>--disable-doctool</systemitem> and
+        <systemitem>--enable-doctool</systemitem></title>
+
+      <para>
+        TODO
+      </para>
+    </formalpara>
+
+    <formalpara>
+      <title><systemitem>--with-python</systemitem></title>
+
+      <para>
+        Allows specifying the Python interpreter to use, either as an
+        absolute path, or as a program name. GObject Introspection can
+        be built with Python 2 (at least version 2.6) but does not yet
+        support Python 3.
+      </para>
+    </formalpara>
+  </refsect1>
+
+</refentry>
diff --git a/docs/reference/overview-programming.xml b/docs/reference/overview-programming.xml
new file mode 100644
index 00000000..6511d4b7
--- /dev/null
+++ b/docs/reference/overview-programming.xml
@@ -0,0 +1,22 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<refentry id="gi-programming">
+  <refmeta>
+    <refentrytitle>Writing introspected libraries</refentrytitle>
+  </refmeta>
+
+  <refnamediv>
+    <refname>Writing introspected libraries</refname>
+    <refpurpose>General considerations when writing introspected libraries</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>TODO</title>
+    <para>
+      ...
+    </para>
+  </refsect1>
+
+</refentry>
diff --git a/docs/reference/version.xml.in b/docs/reference/version.xml.in
index d1cc3c74..fefbcc3d 100644
--- a/docs/reference/version.xml.in
+++ b/docs/reference/version.xml.in
@@ -1,2 +1 @@
-@GOBJECT_INTROSPECTION_VERSION@
-@GOBJECT_INTROSPECTION_VERSION@
+@GI_VERSION@