[docs] Add an overview page

Add an overview page for the documentation with a simple
diagram explaining the relationship between the main components.

5 files changed, 467 insertions, 1 deletions

diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
index 019d2a96..bd1307bd 100644
--- a/docs/reference/Makefile.am
+++ b/docs/reference/Makefile.am
@@ -31,6 +31,15 @@ IGNORE_HFILES= \
 INCLUDES=$(GIREPO_CFLAGS) -I$(top_srcdir)
 GTKDOC_LIBS = $(GIREPO_LIBS) $(top_builddir)/girepository/libgirepository-1.0.la $(top_builddir)/girepository/libgirepository-parser.la
 
+content_files = \
+    gi-gir-reference.xml    \
+    gi-gir.sgml		    \
+    gi-overview.xml	    \
+    gi-struct-hierarchy.xml
+
+HTML_IMAGES = \
+    $(srcdir)/images/overview.png
+
 # Extra options to supply to gtkdoc-fixref
 FIXXREF_OPTIONS=
 
diff --git a/docs/reference/gi-docs.sgml b/docs/reference/gi-docs.sgml
index f3102bc6..4d743c9a 100644
--- a/docs/reference/gi-docs.sgml
+++ b/docs/reference/gi-docs.sgml
@@ -15,8 +15,8 @@
     <para>
 Bla bla bla bla bla
     </para>
+      <xi:include href="gi-overview.xml"/>
 <!--
-    &gi-overview;
     &gi-building;
 -->
   </chapter>
diff --git a/docs/reference/gi-overview.xml b/docs/reference/gi-overview.xml
new file mode 100644
index 00000000..0dc950b3
--- /dev/null
+++ b/docs/reference/gi-overview.xml
@@ -0,0 +1,53 @@
+<?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">
+]>
+<!--ENTITY index-Objects-Grouped SYSTEM "objects_grouped.sgml"-->
+<refentry id="gi-overview">
+<refmeta>
+  <refentrytitle role="top_of_page" id="gi-overview.top_of_page">Introspection Overivew</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/images/overview.png b/docs/reference/images/overview.png
new file mode 100644
index 00000000..52c8619b
--- /dev/null
+++ b/docs/reference/images/overview.png
diff --git a/docs/reference/images/overview.svg b/docs/reference/images/overview.svg
new file mode 100644
index 00000000..b9fa9101
--- /dev/null
+++ b/docs/reference/images/overview.svg
@@ -0,0 +1,404 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="744.09448819"
+   height="1052.3622047"
+   id="svg2"
+   sodipodi:version="0.32"
+   inkscape:version="0.46"
+   sodipodi:docname="overview.svg"
+   inkscape:output_extension="org.inkscape.output.svg.inkscape">
+  <defs
+     id="defs4">
+    <inkscape:perspective
+       sodipodi:type="inkscape:persp3d"
+       inkscape:vp_x="0 : 526.18109 : 1"
+       inkscape:vp_y="0 : 1000 : 0"
+       inkscape:vp_z="744.09448 : 526.18109 : 1"
+       inkscape:persp3d-origin="372.04724 : 350.78739 : 1"
+       id="perspective10" />
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     gridtolerance="10000"
+     guidetolerance="10"
+     objecttolerance="10"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="1.4"
+     inkscape:cx="370.10718"
+     inkscape:cy="776.53594"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     inkscape:window-width="1680"
+     inkscape:window-height="975"
+     inkscape:window-x="1440"
+     inkscape:window-y="25" />
+  <metadata
+     id="metadata7">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1">
+    <rect
+       style="fill:#ffffff;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       id="rect2383"
+       width="678.57141"
+       height="514.28571"
+       x="29.999998"
+       y="25.219318" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#303030;stroke-width:1.02008247;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:4.08032983, 1.02008246;stroke-dashoffset:0;stroke-opacity:0.77586209"
+       d="M 42.877341,295.93361 L 701.40837,295.93361"
+       id="path3171" />
+    <rect
+       style="fill:#bbffff;fill-opacity:1;stroke:#000000;stroke-width:1.06179869;stroke-opacity:0.62780265"
+       id="rect3185"
+       width="186.36678"
+       height="33.509632"
+       x="67.173752"
+       y="224.53593" />
+    <text
+       xml:space="preserve"
+       style="font-size:16px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans"
+       x="76.428574"
+       y="245.93361"
+       id="text3187"><tspan
+         sodipodi:role="line"
+         id="tspan3189"
+         x="76.428574"
+         y="245.93361">Introspected GType's</tspan></text>
+    <g
+       id="g3325"
+       transform="translate(-66.428571,30.714286)">
+      <rect
+         y="102.00188"
+         x="171.78255"
+         height="33.577782"
+         width="109.29207"
+         id="rect3221"
+         style="fill:#bbffff;fill-opacity:1;stroke:#000000;stroke-width:0.99365026;stroke-opacity:0.62780265" />
+      <text
+         id="text3223"
+         y="124.61499"
+         x="185.23328"
+         style="font-size:16px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans"
+         xml:space="preserve"><tspan
+           y="124.61499"
+           x="185.23328"
+           id="tspan3225"
+           sodipodi:role="line">Sources .c</tspan></text>
+    </g>
+    <g
+       id="g3320"
+       transform="translate(-66.428571,30.714286)">
+      <rect
+         y="145.21617"
+         x="170.71114"
+         height="33.577782"
+         width="109.29207"
+         id="rect3183"
+         style="fill:#bbffff;fill-opacity:1;stroke:#000000;stroke-width:0.99365026;stroke-opacity:0.62780265" />
+      <text
+         id="text3227"
+         y="167.96991"
+         x="181.77515"
+         style="font-size:16px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans"
+         xml:space="preserve"><tspan
+           y="167.96991"
+           x="181.77515"
+           id="tspan3229"
+           sodipodi:role="line">Headers .h</tspan></text>
+    </g>
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.6243791px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="M 214.0979,149.31722 L 288.75925,191.83573"
+       id="path3231" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.48916915px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="M 254.74458,239.76045 L 288.82684,192.82106"
+       id="path3235" />
+    <rect
+       style="fill:#87ffa1;fill-opacity:1;stroke:#000000;stroke-width:1.30141628;stroke-opacity:1"
+       id="rect3247"
+       width="208.27"
+       height="135.41287"
+       x="289.4364"
+       y="133.9415" />
+    <text
+       xml:space="preserve"
+       style="font-size:16px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans"
+       x="295.99329"
+       y="156.75784"
+       id="text3249"><tspan
+         sodipodi:role="line"
+         x="295.99329"
+         y="156.75784"
+         id="tspan3463">GIR verbose XML format</tspan><tspan
+         sodipodi:role="line"
+         x="295.99329"
+         y="176.75784"
+         id="tspan3469">with introspectable</tspan><tspan
+         sodipodi:role="line"
+         x="295.99329"
+         y="196.75784"
+         id="tspan3495">metdata a language</tspan><tspan
+         sodipodi:role="line"
+         x="295.99329"
+         y="216.75784"
+         id="tspan3471">binding need, function,</tspan><tspan
+         sodipodi:role="line"
+         x="295.99329"
+         y="236.75784"
+         id="tspan3491">class,enum,docstrings,</tspan><tspan
+         sodipodi:role="line"
+         x="295.99329"
+         y="256.75784"
+         id="tspan3515">struct fields etc</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:16px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans"
+       x="227.14287"
+       y="107.36218"
+       id="text3253"><tspan
+         sodipodi:role="line"
+         id="tspan3255"
+         x="227.14287"
+         y="107.36218">g-ir-scanner(1)</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:16px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans"
+       x="541.42859"
+       y="107.36218"
+       id="text3257"><tspan
+         sodipodi:role="line"
+         id="tspan3259"
+         x="541.42859"
+         y="107.36218">g-ir-compiler(1)</tspan></text>
+    <path
+       style="fill:none;fill-opacity:0.35426007;fill-rule:evenodd;stroke:#000000;stroke-width:1.28129315;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:3.84387917, 3.84387917;stroke-dashoffset:0;stroke-opacity:0.48878922"
+       d="M 513.92858,92.402021 L 513.92858,282.32233"
+       id="path3265" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="M 212.85714,193.79075 L 287.85714,193.79075"
+       id="path3279" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.68055099px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="M 499.4176,193.07647 L 534.15382,193.07647"
+       id="path3281" />
+    <g
+       id="g3473"
+       transform="translate(24.285714,13.571429)">
+      <rect
+         y="130.21986"
+         x="510.00055"
+         height="105.71322"
+         width="157.85606"
+         id="rect3277"
+         style="fill:#b5ff87;fill-opacity:1;stroke:#000000;stroke-width:1.00107861;stroke-opacity:1" />
+      <text
+         id="text3283"
+         y="153.20482"
+         x="526.4989"
+         style="font-size:16px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans"
+         xml:space="preserve"><tspan
+           y="153.20482"
+           x="526.4989"
+           id="tspan3285"
+           sodipodi:role="line">Typelib - binary</tspan><tspan
+           id="tspan3457"
+           y="173.20482"
+           x="526.4989"
+           sodipodi:role="line">format for fast</tspan><tspan
+           id="tspan3459"
+           y="193.20482"
+           x="526.4989"
+           sodipodi:role="line">disk-access and</tspan><tspan
+           id="tspan3461"
+           y="213.20482"
+           x="526.4989"
+           sodipodi:role="line">low memory</tspan></text>
+    </g>
+    <text
+       xml:space="preserve"
+       style="font-size:16px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans"
+       x="44.285713"
+       y="56.647896"
+       id="text3297"><tspan
+         sodipodi:role="line"
+         id="tspan3299"
+         x="44.285713"
+         y="56.647896"
+         style="font-size:20px;font-weight:bold;-inkscape-font-specification:Bitstream Vera Sans Bold">Build time</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:16px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans"
+       x="48.293804"
+       y="329.10397"
+       id="text3301"><tspan
+         sodipodi:role="line"
+         x="48.293804"
+         y="329.10397"
+         style="font-size:20px;font-weight:bold;-inkscape-font-specification:Bitstream Vera Sans Bold"
+         id="tspan3305">Runtime</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:16px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans"
+       x="244.28571"
+       y="118.79075"
+       id="text3312"><tspan
+         sodipodi:role="line"
+         id="tspan3314"></tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:16px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans"
+       x="244.28571"
+       y="118.79075"
+       id="text3316"><tspan
+         sodipodi:role="line"
+         id="tspan3318"></tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:12px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans"
+       x="67.14286"
+       y="350.21933"
+       id="text3342"><tspan
+         sodipodi:role="line"
+         id="tspan3344"
+         x="67.14286"
+         y="350.21933"
+         style="font-style:italic;font-variant:normal;font-weight:normal;font-stretch:normal;font-family:Bitstream Vera Serif;-inkscape-font-specification:Bitstream Vera Serif Italic">How a language binding uses introspection</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:12px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans"
+       x="66.887283"
+       y="79.159195"
+       id="text3346"><tspan
+         sodipodi:role="line"
+         id="tspan3348"
+         x="66.887283"
+         y="79.159195"
+         style="font-style:italic;font-variant:normal;font-weight:normal;font-stretch:normal;font-family:Bitstream Vera Serif;-inkscape-font-specification:Bitstream Vera Serif Italic">How a library enables introspection</tspan></text>
+    <rect
+       style="fill:#b5ff87;fill-opacity:1;stroke:#000000;stroke-width:1.0904454;stroke-opacity:1"
+       id="rect3359"
+       width="191.33812"
+       height="103.481"
+       x="80.402374"
+       y="385.97882" />
+    <text
+       xml:space="preserve"
+       style="font-size:16px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans"
+       x="109.08316"
+       y="422.13339"
+       id="text3361"><tspan
+         sodipodi:role="line"
+         id="tspan3363"
+         x="109.08316"
+         y="422.13339">Typelib - mmap()</tspan><tspan
+         sodipodi:role="line"
+         x="109.08316"
+         y="442.13339"
+         id="tspan3395">shared between</tspan><tspan
+         sodipodi:role="line"
+         x="109.08316"
+         y="462.13339"
+         id="tspan3397">processes</tspan></text>
+    <g
+       id="g3413"
+       transform="translate(-30.714286,3.5714286)">
+      <rect
+         y="388.51193"
+         x="366.86404"
+         height="43.41486"
+         width="148.41486"
+         id="rect3376"
+         style="fill:#ffcf87;fill-opacity:1;stroke:#000000;stroke-width:0.44228357;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:0.48878922" />
+      <text
+         id="text3380"
+         y="414.63342"
+         x="383.2746"
+         style="font-size:16px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans"
+         xml:space="preserve"><tspan
+           y="414.63342"
+           x="383.2746"
+           id="tspan3382"
+           sodipodi:role="line">libgirepository</tspan></text>
+    </g>
+    <g
+       id="g3418"
+       transform="translate(-30,3.5714286)">
+      <rect
+         y="445.21933"
+         x="367.14288"
+         height="37.142857"
+         width="147.85715"
+         id="rect3384"
+         style="fill:#ffcf87;fill-opacity:1;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:0.48878922" />
+      <text
+         id="text3386"
+         y="469.75562"
+         x="423.70425"
+         style="font-size:16px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans"
+         xml:space="preserve"><tspan
+           y="469.75562"
+           x="423.70425"
+           id="tspan3388"
+           sodipodi:role="line">libffi</tspan></text>
+    </g>
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.82769597px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="M 272.05671,437.35287 L 335.08615,412.27603"
+       id="path3399" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.83396173px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="M 271.62195,443.79905 L 336.51159,469.58806"
+       id="path3401" />
+    <rect
+       style="fill:#bbffff;fill-opacity:1;stroke:#000000;stroke-width:0.88915378;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:0.48878922"
+       id="rect3403"
+       width="152.96799"
+       height="41.539417"
+       x="529.23022"
+       y="418.02109" />
+    <text
+       xml:space="preserve"
+       style="font-size:16px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans"
+       x="537.24548"
+       y="443.20486"
+       id="text3405"><tspan
+         sodipodi:role="line"
+         id="tspan3407"
+         x="537.24548"
+         y="443.20486">dlopen:ed library</tspan></text>
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.21470141px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="M 484.39306,412.46952 L 529.17837,437.96912"
+       id="path3409" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.19193971px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="M 485.09597,466.55192 L 529.18975,440.3153"
+       id="path3411" />
+  </g>
+</svg>