[tepl] intro: move more README content to reference manual

[Sébastien Wilmet <swilmet src gnome org>]

commit f0e4c4db8e214c2b6efc192576266194b84b3683
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Mon Jun 12 07:31:02 2017 +0200

    intro: move more README content to reference manual
    
    The two wiki links for the background info are now present on:
    https://wiki.gnome.org/Projects/Tepl

 README                      |   36 +++---------------------------------
 docs/reference/intro.xml.in |   41 +++++++++++++++++++++++++++++++++++++----
 2 files changed, 40 insertions(+), 37 deletions(-)
---
diff --git a/README b/README
index 7c88caa..d225b84 100644
--- a/README
+++ b/README
@@ -10,42 +10,12 @@ Tepl was previously known as Gtef (GTK+ text editor framework). The project has
 been renamed in June 2017 to have a more beautiful name. The end of Tepl is
 pronounced like “apple”.
 
-The Tepl website:
-
-    https://wiki.gnome.org/Projects/Tepl
-
-Some background on why this project has been created:
-
-    https://wiki.gnome.org/Apps/Gedit/ReusableCode
-    https://wiki.gnome.org/Projects/GtkSourceView/TdiFramework
-
-Maybe some of the Tepl features will be moved to GtkSourceView when it's
-considered more stable. So Tepl can also be seen as an incubator for some
-GtkSourceView features.
-
 The Tepl library is free software and is released under the terms of the GNU
 Lesser General Public License, see the 'COPYING' file for more information.
 
-Warning - API/ABI stability
----------------------------
-
-Tepl uses the same versioning *scheme* as GNOME, but not the same version
-*numbers* at the same time. The package version has the form
-'major.minor.micro'. If 'minor' is an even number, it means that it is a stable
-version and that API/ABI stability is guaranteed, and that it is
-backward-compatible with previous stable minor versions that have the same
-major version (e.g. 1.2.x is backward-compatible with 1.0.x). When a new major
-version is released, it means that the API or ABI is not backward-compatible
-with previous major versions. Different major versions can be installed in
-parallel.
-
-To learn more about the GNOME versioning scheme:
-https://developer.gnome.org/programming-guidelines/stable/versioning.html.en
-
-Tepl contains more experimental APIs than GtkSourceView, sometimes even
-unfinished features. It means that - if needed - new major versions are
-released every 6 months, breaking the API to improve and design it
-incrementally.
+The Tepl web page:
+
+    https://wiki.gnome.org/Projects/Tepl
 
 Dependencies
 ------------
diff --git a/docs/reference/intro.xml.in b/docs/reference/intro.xml.in
index 8fb161c..78daec5 100644
--- a/docs/reference/intro.xml.in
+++ b/docs/reference/intro.xml.in
@@ -17,6 +17,10 @@
   </para>
 
   <para>
+    See the <ulink url="https://wiki.gnome.org/Projects/Tepl";>Tepl web page</ulink>.
+  </para>
+
+  <para>
     Tepl was previously known as Gtef (GTK+ text editor framework). The project
     has been renamed in June 2017 to have a more beautiful name. The end of Tepl
     is pronounced like “apple”.
@@ -40,12 +44,41 @@
   </para>
 
   <para>
-    See also the <ulink url="https://wiki.gnome.org/Projects/Tepl";>Tepl web page</ulink>.
+    Maybe some of the Tepl features will be moved to GtkSourceView when it's
+    considered more stable. So Tepl can also be seen as an incubator for some
+    GtkSourceView features.
   </para>
 
-  <para>
-    Tepl @TEPL_API_VERSION@ depends on GTK+ 3 and GtkSourceView 3.
-  </para>
+  <refsect1>
+    <title>Iterative API design and stability guarantees</title>
+
+    <para>
+      Tepl uses the same
+      <ulink url="https://developer.gnome.org/programming-guidelines/stable/versioning.html.en";>versioning 
scheme</ulink>
+      as GNOME. API/ABI stability is guaranteed. For example Tepl 3.2 is
+      backward-compatible with Tepl 3.0 (those versions don't necessarily exist,
+      it's just an example). But the peculiarity of Tepl is that new major
+      versions are released more often, at most every 6 months if needed.
+      Different major versions can be installed in parallel, like GTK+&nbsp;2
+      and GTK+&nbsp;3.
+    </para>
+
+    <para>
+      New major versions are released more often because Tepl contains more
+      experimental APIs than GtkSourceView, sometimes even unfinished features.
+      API design is hard, it needs an iterative process. Instead of being stuck
+      for years with a non-optimal API, the Tepl developers want to be able to
+      break the API at any time, to iteratively improve it. Sometimes we see
+      possible improvements several years later.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>GTK+ and GtkSourceView dependencies</title>
+    <para>
+      Tepl @TEPL_API_VERSION@ depends on GTK+ 3 and GtkSourceView 3.
+    </para>
+  </refsect1>
 
   <refsect1>
     <title>pkg-config name</title>