[gtksourceview] docs: add a porting guide for GtkSourceView 3 -> 4

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

commit f2aaa48083a8aa49455a602c038bb25222094b6f
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Sun Nov 13 17:19:36 2016 +0100

    docs: add a porting guide for GtkSourceView 3 -> 4

 docs/reference/Makefile.am               |    1 +
 docs/reference/gtksourceview-docs.xml.in |    2 +
 docs/reference/porting-guide.xml         |   74 ++++++++++++++++++++++++++++++
 3 files changed, 77 insertions(+), 0 deletions(-)
---
diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
index 7e5b20c..32fc503 100644
--- a/docs/reference/Makefile.am
+++ b/docs/reference/Makefile.am
@@ -76,6 +76,7 @@ content_files =                       \
        intro.xml               \
        lang-tutorial.xml       \
        lang-reference.xml      \
+       porting-guide.xml       \
        style-reference.xml
 
 # Extra options to supply to gtkdoc-fixref
diff --git a/docs/reference/gtksourceview-docs.xml.in b/docs/reference/gtksourceview-docs.xml.in
index 943243a..e99fc0c 100644
--- a/docs/reference/gtksourceview-docs.xml.in
+++ b/docs/reference/gtksourceview-docs.xml.in
@@ -98,6 +98,8 @@
     <xi:include href="style-reference.xml"/>
   </part>
 
+  <xi:include href="porting-guide.xml"/>
+
   <part>
     <title>Annexes</title>
 
diff --git a/docs/reference/porting-guide.xml b/docs/reference/porting-guide.xml
new file mode 100644
index 0000000..3defbae
--- /dev/null
+++ b/docs/reference/porting-guide.xml
@@ -0,0 +1,74 @@
+<?xml version="1.0"?>
+<!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 % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
+ %gtkdocentities;
+]>
+
+<part>
+  <title>GtkSourceView 3 -> 4 Porting Guide</title>
+
+  <refsect1>
+    <title>GTK+ dependency</title>
+    <para>
+      Both GtkSourceView 3 and GtkSourceView 4 depend on GTK+ 3. GtkSourceView 5
+      depends on GTK+ 4. Before porting an application to GTK+ 4, it is
+      therefore recommended to first port to GtkSourceView 4 and then to GTK+ 4
+      and GtkSourceView 5.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Preparation in GtkSourceView 3</title>
+    <para>
+      GtkSourceView 3.24 is the latest stable GtkSourceView 3 version. You
+      should use this version without using any deprecated API.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>New pkg-config name</title>
+    <para>
+      For GtkSourceView 4, the pkg-config name is:
+      <code>gtksourceview-4</code>
+    </para>
+    <para>
+      To compile a program that uses GtkSourceView 4, you
+      can for example use the following command:
+    </para>
+    <para>
+      <code>$ gcc hello.c `pkg-config --cflags --libs gtksourceview-4` -o hello</code>
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>A set of intermediate tarballs to ease the transition</title>
+    <para>
+      When porting to GtkSourceView 4, instead of doing everything in one step,
+      you can compile intermediate 3.99.x tarballs of GtkSourceView, so that you
+      can compile your code regularly and run the tests. Not doing all at once
+      in one big commit, but instead doing smaller and testable commits.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>GtkSourceView 3.99.1</title>
+    <itemizedlist>
+      <listitem>
+        <para>
+          All the deprecated APIs have been removed.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Only the version 2 of the <link linkend="lang-reference">GtkSourceView
+          language definition file format</link> is supported (for *.lang files,
+          used for syntax highlighting). The support for the version 1 has been
+          dropped.
+        </para>
+      </listitem>
+    </itemizedlist>
+  </refsect1>
+</part>