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

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

commit a4858f2bd3f3fae911911fcdf788a8a377fbd8c2
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/gtksourceview-docs.xml.in |    2 +
 docs/reference/porting-guide.xml         |   74 ++++++++++++++++++++++++++++++
 2 files changed, 76 insertions(+), 0 deletions(-)
---
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..4c1a754
--- /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 huge 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>