[tepl] docs: update/improve the intro

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

commit 84d8a02fa3656ef91db8b132d4e04f488b39be22
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Thu Jul 27 18:00:02 2017 +0200

    docs: update/improve the intro

 docs/reference/intro.xml.in |   36 +++++++++++++++++++++++++-----------
 1 files changed, 25 insertions(+), 11 deletions(-)
---
diff --git a/docs/reference/intro.xml.in b/docs/reference/intro.xml.in
index 041b160..f119649 100644
--- a/docs/reference/intro.xml.in
+++ b/docs/reference/intro.xml.in
@@ -78,20 +78,23 @@
       object in GtkSourceView is the <link linkend="GtkSourceView">GtkSourceView</link>
       widget (representing only one view, or one file), while the GtkSourceView
       widget is at the bottom of the containment hierarchy in the Tepl
-      framework. The top-level object in Tepl is
-      <link linkend="TeplApplication">TeplApplication</link>, representing the
-      whole application which can contain several windows, with each window
-      containing one or several GtkSourceView widgets (typically with a Tabbed
-      Document Interface).
+      framework (it is a “somewhat” clear boundary because there is also
+      <link linkend="TeplBuffer">TeplBuffer</link>, a subclass of
+      <link linkend="GtkSourceBuffer">GtkSourceBuffer</link>).
     </para>
 
-    <!-- TODO Once the framework is complete, update paragraph. -->
     <para>
-      So the GtkSourceView library is not aware that there can be several
-      documents opened in the application, while the Tepl framework –&nbsp;once
-      finished&nbsp;– will have a complete view of the application with regards
-      to the opened documents. It permits to implement higher-level APIs in
-      Tepl.
+      The top-level object in Tepl is <link linkend="TeplApplication">TeplApplication</link>,
+      representing the whole application which can contain several windows, with
+      each window containing one or several GtkSourceView widgets (typically
+      with a Tabbed Document Interface).
+    </para>
+
+    <para>
+      So the GtkSourceView library is not aware that there can be several files
+      opened in the application, while the Tepl framework has a complete view of
+      the application with regards to the opened files/tabs. It permits to
+      implement higher-level APIs.
     </para>
   </refsect1>
 
@@ -117,6 +120,17 @@
       break the API at any time, to iteratively improve it. Sometimes we see
       possible improvements several years later.
     </para>
+
+    <para>
+      So applications depending on an old (stable) vesion of Tepl will still
+      compile and run fine, and the Tepl developers can develop the library with
+      more freedom.
+    </para>
+
+    <para>
+      The API breaks are well documented in
+      <link linkend="api-breaks">this section</link>.
+    </para>
   </refsect1>
 
   <refsect1>