[gtksourceview: 8/21] docs: port the migration guide from 4 -> 5 to markdown

[Christian Hergert <chergert src gnome org>]

commit 8910ee57a0ead6b205bf8091ce1fb86df53cc58f
Author: Bilal Elmoussaoui <bil elmoussaoui gmail com>
Date:   Tue Nov 30 18:12:36 2021 +0100

    docs: port the migration guide from 4 -> 5 to markdown

 docs/GtkSource.toml.in                  |   1 +
 docs/porting-guide-4-to-5.md            |  69 ++++++++++++++++++++++
 docs/reference/meson.build              |   1 -
 docs/reference/porting-guide-4-to-5.xml | 100 --------------------------------
 4 files changed, 70 insertions(+), 101 deletions(-)
---
diff --git a/docs/GtkSource.toml.in b/docs/GtkSource.toml.in
index 79fd4111..121e3e43 100644
--- a/docs/GtkSource.toml.in
+++ b/docs/GtkSource.toml.in
@@ -56,6 +56,7 @@ show_class_hierarchy = true
 # The same order will be used when generating the index
 content_files = [
   "porting-guide-3-to-4.md",
+  "porting-guide-4-to-5.md",
 ]
 
 content_images = [
diff --git a/docs/porting-guide-4-to-5.md b/docs/porting-guide-4-to-5.md
new file mode 100644
index 00000000..e14a29c3
--- /dev/null
+++ b/docs/porting-guide-4-to-5.md
@@ -0,0 +1,69 @@
+Title: GtkSourceView 4 -> 5 Migration Guide
+
+# GtkSourceView 4 -> 5 Migration Guide
+
+## GTK+ dependency
+
+GtkSourceView 5 depends on GTK 4.
+
+## GtkSourceGutterRenderer is a GtkWidget
+
+In GtkSourceView 5, the [class@GutterRenderer] has become a widget.
+This allows more flexibility by implementations to handle input as well
+as cache snapshot information for faster rendering.
+
+## GtkSourceGutterLines
+
+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.
+
+In GtkSourceView 5, a [class@GutterLines] structure has been added to the
+API which allows for collecting that information and re-using by each
+gutter renderer, thus reducing overhead greatly.
+
+[class@GutterRenderer] implementations should use this to store
+information about each line and then recall it when snapshotting the
+given line.
+
+## GtkSourceSnippet
+
+GtkSourceView 5 added support for snippets. This functionality did not
+exist within previous versions of GtkSourceView.
+
+The implementation contains a snippet language embedded within XML files
+as well as a completion provider. You may also "push" snippets onto a
+[class@View] manually by creating [class@SnippetChunk] and associating
+them with a [class@Snippet]. Many completion providers may find this more
+convenient to allow users to move through focus positions.
+
+## GtkSourceCompletion
+
+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.
+
+[class@CompletionProposal] no longer requires any implementation except
+to implement the interface symbolically. That can be done using
+`G_IMPLEMENT_INTERFACE(GTK_SOURCE_TYPE_COMPLETION_PROPOSAL,NULL)`.
+This allowed all of the implementation details to be placed in
+[iface@CompletionProvider].
+
+[class@CompletionCell] is a new display widget that is used
+in multiple places as a generic container for information about completion
+proposals.
+
+[iface@CompletionProvider]s are now expected to asynchronously
+provide a [iface@Gio.ListModel] of [class@CompletionProposal]
+instead of a `GList`. 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 [method@CompletionContext.set_proposals_for_provider].
+
+## Style Schemes
+
+Since 5.2, GtkSourceView will synthesize an appropriate background color
+for current-line-number if current-line-number’s background is not specified.
+Style schemes which have not already set current-line-number should be updated
+and use `#rgba(0,0,0,0)` to match the previous behavior.
diff --git a/docs/reference/meson.build b/docs/reference/meson.build
index 4d329570..241bb799 100644
--- a/docs/reference/meson.build
+++ b/docs/reference/meson.build
@@ -63,7 +63,6 @@ reference_private_h = [
 
 reference_content_files = files([
   'lang-tutorial.xml',
-  'porting-guide-4-to-5.xml',
 ])
 
 reference_sources = [