docs: move some tutorial content to the reference

We add a "Getting started" chapter that will grow into a
(hopefully) non-outdated, maintained tutorial. For now, it
includes two minimal examples by xincluding them.

5 files changed, 21 insertions, 101 deletions

diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am
index 0140db6cb3..162eb2e50e 100644
--- a/docs/reference/gtk/Makefile.am
+++ b/docs/reference/gtk/Makefile.am
@@ -133,7 +133,8 @@ content_files =					\
 	gtk-update-icon-cache-3.0.xml		\
 	gtk-builder-convert-3.0.xml		\
 	visual_index.xml			\
-	getting_started.xml
+	getting_started.xml			\
+	overview.xml
 
 expand_content_files = 				\
 	drawing-model.xml			\
@@ -317,7 +318,9 @@ HTML_IMAGES = \
 	$(srcdir)/images/layout-rlbt.png				\
 	$(srcdir)/images/layout-rltb.png				\
 	$(srcdir)/images/layout-tblr.png				\
-	$(srcdir)/images/layout-tbrl.png
+	$(srcdir)/images/layout-tbrl.png				\
+	$(srcdir)/images/window-default.png				\
+	$(srcdir)/images/hello-world.png
 
 # Extra options to supply to gtkdoc-fixref
 FIXXREF_OPTIONS=--extra-dir=../gdk/html \
diff --git a/docs/reference/gtk/getting_started.xml b/docs/reference/gtk/getting_started.xml
index 8ce21b900b..ddbff64f8f 100644
--- a/docs/reference/gtk/getting_started.xml
+++ b/docs/reference/gtk/getting_started.xml
@@ -5,8 +5,16 @@
 <chapter id="gtk-getting-started" xmlns:xi="http://www.w3.org/2003/XInclude">
   <title>Getting Started with GTK+</title>
 
+  <para>This chapter is contains some tutorial information to get you
+  started with GTK+ programming. It assumes that you have GTK+, its
+  dependencies and a C compiler installed and ready to use. If you
+  need to build GTK+ itself first, refer to the
+  <link linkend="gtk-compiling">Compiling the GTK+ libraries</link>
+  section in this reference.</para>
+
   <para>To begin our introduction to GTK, we'll start with the simplest
-  program possible. This program will create a 200x200 pixel window:</para>
+  program possible. This program will create an empty 200x200 pixel
+  window:</para>
 
   <para>
     <inlinegraphic fileref="window-default.png" format="PNG"></inlinegraphic>
@@ -84,10 +92,14 @@
   <para>In the long tradition of programming languages and libraries,
   it is called <emphasis>Hello, World</emphasis>.</para>
 
+  <para>
+    <inlinegraphic fileref="hello-world.png" format="PNG"></inlinegraphic>
+  </para>
+
   <example id="gtk-getting-started-hello-world">
     <title>Hello World in GTK+</title>
     <programlisting>
-      <xi:include href="../../../examples/hello-world.c" parse="text">
+      <xi:include href="../../../../examples/hello-world.c" parse="text">
         <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
       </xi:include>
     </programlisting>
diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml
index d089e86413..7faf5122c6 100644
--- a/docs/reference/gtk/gtk-docs.sgml
+++ b/docs/reference/gtk/gtk-docs.sgml
@@ -16,106 +16,11 @@
 
   <part id="gtk">
     <title>GTK+ Overview</title>
-    <partintro>
-    <para>
-GTK+ is a library for creating graphical user interfaces. It
-works on many UNIX-like platforms, Windows, and OS X.
-GTK+ is released under the GNU Library General Public License
-(GNU LGPL), which allows for flexible licensing of client
-applications. GTK+ has a C-based object-oriented architecture that
-allows for maximum flexibility.  Bindings for many other languages have
-been written, including C++, Objective-C, Guile/Scheme, Perl, Python,
-TOM, Ada95, Free Pascal, and Eiffel.
-    </para>
-    <para>
-GTK+ depends on the following libraries:
-<variablelist>
-
-<varlistentry>
-<term>GLib</term>
-<listitem><para>
-A general-purpose utility library, not specific to graphical user interfaces.
-GLib provides many useful data types, macros, type conversions,
-string utilities, file utilities, a main loop abstraction, and so on.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>GObject</term>
-<listitem><para>A library that provides a type system, a collection of
-fundamental types including an object type, a signal system.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>GIO</term>
-<listitem><para>A modern, easy-to-use VFS API including abstractions for
-files, drives, volumes, stream IO, as well as network programming and
-DBus communication.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>cairo</term>
-<listitem><para>Cairo is a 2D graphics library with support for multiple
-output devices.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>Pango</term>
-<listitem><para>
-Pango is a library for internationalized text handling. It centers
-around the PangoLayout object, representing a paragraph of text.
-Pango provides the engine for GtkTextView, GtkLabel, GtkEntry, and
-other widgets that display text.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>ATK</term>
-<listitem><para>
-ATK is the Accessibility Toolkit. It provides a set of generic
-interfaces allowing accessibility technologies to interact with a
-graphical user interface. For example, a screen reader uses ATK to
-discover the text in an interface and read it to blind users.  GTK+
-widgets have built-in support for accessibility using the ATK
-framework.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>GdkPixbuf</term>
-<listitem><para>
-This is a small library which allows you to create GdkPixbuf
-("pixel buffer") objects from image data or image files.
-Use a GdkPixbuf in combination with GtkImage to display images.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>GDK</term>
-<listitem><para>
-GDK is the abstraction layer that allows GTK+ to support multiple
-windowing systems. GDK provides window system facilities on X11, Windows,
-and OS X.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>GTK+</term>
-<listitem><para>
-The GTK+ library itself contains <firstterm>widgets</firstterm>,
-that is, GUI components such as GtkButton or GtkTextView.
-</para></listitem>
-</varlistentry>
-</variablelist>
-    </para>
-</partintro>
+    <xi:include href="overview.xml"/>
+    <xi:include href="xml/getting_started.xml"/>
     <xi:include href="building.sgml" />
     <xi:include href="compiling.sgml" />
     <xi:include href="running.sgml" />
-    <xi:include href="xml/getting_started.xml"/>
     <xi:include href="x11.sgml" />
     <xi:include href="windows.sgml" />
     <xi:include href="osx.sgml" />
diff --git a/docs/reference/gtk/images/hello-world.png b/docs/reference/gtk/images/hello-world.png
new file mode 100644
index 0000000000..acf7aaff8f
--- /dev/null
+++ b/docs/reference/gtk/images/hello-world.png
diff --git a/docs/reference/gtk/images/window-default.png b/docs/reference/gtk/images/window-default.png
new file mode 100644
index 0000000000..40245c4b6c
--- /dev/null
+++ b/docs/reference/gtk/images/window-default.png