[gtksourceview] doc: start on migration guide for 5.x

[Christian Hergert <chergert src gnome org>]

commit 7eb9abe0f4bc53b0636bddcac0589b5b3dbe8cdc
Author: Christian Hergert <chergert redhat com>
Date:   Mon Sep 21 17:41:21 2020 -0700

    doc: start on migration guide for 5.x

 docs/reference/gtksourceview-docs.xml.in |  3 +-
 docs/reference/porting-guide-3-to-4.xml  |  2 +-
 docs/reference/porting-guide-4-to-5.xml  | 92 ++++++++++++++++++++++++++++++++
 3 files changed, 95 insertions(+), 2 deletions(-)
---
diff --git a/docs/reference/gtksourceview-docs.xml.in b/docs/reference/gtksourceview-docs.xml.in
index 89e3bd49..89d004e8 100644
--- a/docs/reference/gtksourceview-docs.xml.in
+++ b/docs/reference/gtksourceview-docs.xml.in
@@ -112,8 +112,9 @@
   </part>
 
   <part id="porting-guide">
-    <title>Porting Guide</title>
+    <title>Migration Guide</title>
     <xi:include href="porting-guide-3-to-4.xml"/>
+    <xi:include href="porting-guide-4-to-5.xml"/>
   </part>
 
   <part id="annexes">
diff --git a/docs/reference/porting-guide-3-to-4.xml b/docs/reference/porting-guide-3-to-4.xml
index e7591bba..8312edb7 100644
--- a/docs/reference/porting-guide-3-to-4.xml
+++ b/docs/reference/porting-guide-3-to-4.xml
@@ -6,7 +6,7 @@
 ]>
 
 <chapter id="porting-guide-3-to-4">
-  <title>GtkSourceView 3 -> 4 Porting Guide</title>
+  <title>GtkSourceView 3 -> 4 Migration Guide</title>
 
   <refsect1>
     <title>GTK+ dependency</title>
diff --git a/docs/reference/porting-guide-4-to-5.xml b/docs/reference/porting-guide-4-to-5.xml
new file mode 100644
index 00000000..5c200ef2
--- /dev/null
+++ b/docs/reference/porting-guide-4-to-5.xml
@@ -0,0 +1,92 @@
+<?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'">
+]>
+
+<chapter id="porting-guide-4-to-5">
+  <title>GtkSourceView 4 -> 5 Migration Guide</title>
+
+  <refsect1>
+    <title>GTK+ dependency</title>
+    <para>
+      GtkSourceView 5 depends on GTK 4.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>GtkSourceGutterRenderer is a GtkWidget</title>
+    <para>
+      In GtkSourceView 5, the GtkSourceGutterRenderer has become a widget.
+      This allows more flexibility by implementations to handle input as well
+      as cache snapshot information for faster rendering.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>GtkSourceGutterLines</title>
+    <para>
+      Previously, GtkSourceView would spend a lot of time while scrolling just
+      for rendering the gutter. This was because it had to calculate much line
+      information on every frame (roughly 60 frames per second) and multiple
+      times within that frame.
+    </para>
+    <para>
+      In GtkSourceView 5, a GtkSourceGutterLines structure has been added to the
+      API which allows for collecting that information and re-using by each
+      gutter renderer, thus reducing overhead greatly.
+    </para>
+    <para>
+      GtkSourceGutterRenderer implementations should use this to store
+      information about each line and then recall it when snapshotting the
+      given line.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>GtkSourceSnippet</title>
+    <para>
+      GtkSourceView 5 added support for snippets. This functionality did not
+      exist within previous versions of GtkSourceView.
+    </para>
+    <para>
+      The implementation contains a snippet language embedded within XML files
+      as well as a completion provider. You may also "push" snippets onto a
+      GtkSourceView manually by creating GtkSourceSnippetChunks and associating
+      them with a GtkSourceSnippet. Many completion providers may find this more
+      convenient to allow users to move through focus positions.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>GtkSourceCompletion</title>
+    <para>
+      GtkSourceView 5 changed how completion providers are implemented. Doing so
+      has allowed for much reduction in overhead when generating results and
+      presenting them to the user. Additionally, it has improved Wayland support
+      for placing completion results.
+    </para>
+    <para>
+      GtkSourceCompletionProposal no longer requires any implementation except
+      to implement the interface symbolically. That can be done using
+      <code>G_IMPLEMENT_INTERFACE(GTK_SOURCE_TYPE_COMPLETION_PROPOSAL,NULL)</code>.
+      This allowed all of the implementation details to be placed in
+      <code>GtkSourceCompletionProvider</code>.
+    </para>
+    <para>
+      <code>GtkSourceCompletionCell</code> is a new display widget that is used
+      in multiple places as a generic container for information about completion
+      proposals.
+    </para>
+    <para>
+      <code>GtkSourceCompletionProvider</code>s are now expected to asynchronously
+      provide a <code>GListModel</code> of <code>GtkSourceCompletionProposal</code>
+      instead of a <code>GList</code>. Refiltering of results can be provided using
+      the refilter method and should be updated while the user types further. If a
+      new model must be generated, use
+      <link 
linkend="gtk-source-completion-context-set-proposals-for-provider">gtk_source_completion_context_set_proposals_for_provider()</link>.
+    </para>
+  </refsect1>
+
+</chapter>