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

3 files changed, 66 insertions, 176 deletions

diff --git a/docs/porting-guide-3-to-4.md b/docs/porting-guide-3-to-4.md
new file mode 100644
index 00000000..b5a77f9c
--- /dev/null
+++ b/docs/porting-guide-3-to-4.md
@@ -0,0 +1,66 @@
+Title: GtkSourceView 3 -> 4 Migration Guide
+
+# GtkSourceView 3 -> 4 Migration Guide
+
+## Dependencies
+
+Both GtkSourceView 3 and GtkSourceView 4 depend on GTK+ 3.
+
+## Preparation in GtkSourceView 3
+
+GtkSourceView 3.24 is the latest stable GtkSourceView 3 version. Before
+continuing this porting guide, you should use the 3.24 version without
+using any deprecated API.
+
+## New pkg-config name
+
+For GtkSourceView 4, the pkg-config name is: `gtksourceview-4`
+To compile a program that uses GtkSourceView 4, you
+can for example use the following command:
+
+```
+$ gcc hello.c "pkg-config --cflags --libs gtksourceview-4" -o hello
+```
+
+## GtkSourceView 3.99.1
+
+- All the deprecated APIs have been removed.
+- Only `<gtksourceview/gtksource.h>` can be included directly. There were already warnings about it in GtkSourceView 3. The warnings have been changed to errors.
+
+- Only the version 2 of the [GtkSourceView language definition file format](./lang-reference.html) is supported (for *.lang files, used for syntax highlighting). The support for the version 1 has been
+dropped.
+
+## GtkSourceView 3.99.2
+
+- `gtk_source_completion_item_new2()` has been renamed to `gtk_source_completion_item_new()`
+- `gtk_source_search_context_forward2()` has been renamed to [method@SearchContext.forward].
+- `gtk_source_search_context_forward_finish2()` has been renamed to [method@SearchContext.forward_finish].
+- `gtk_source_search_context_backward2()` has been renamed to [method@SearchContext.backward].
+- `gtk_source_search_context_backward_finish2()` has been renamed to [method@SearchContext.backward_finish].
+- `gtk_source_search_context_replace2()` has been renamed to [method@SearchContext.replace].
+- The [property@SearchContext:settings] property is now construct-only.
+
+## GtkSourceView 3.99.3
+
+No API changes.
+
+## GtkSourceView 3.99.4
+
+The API of the [signal@View::move-lines] keybinding signal has been simplified:
+
+- The `copy` parameter was deprecated and has been removed
+- The `count` parameter has been replaced by the `down` boolean.
+
+## GtkSourceView 3.99.5 and 3.99.6
+
+No API changes.
+
+## GtkSourceView 3.99.7
+
+In order to have a better *.gir file and have less metadata to generate the `*.vapi` for Vala, the following change has been made:
+
+- `gtk_source_completion_show()` has been renamed to `gtk_source_completion_start()`. The function conflicted with the [signal@Completion::show] signal.
+Note that in Vala this doesn't require code changes because the method was already renamed to `start()` in GtkSourceView 3.
+
+- For i18n initialization, the [func@init] function now needs to be called. There is also the [func@finalize]
+function which is convenient when using memory debugging tools.
diff --git a/docs/reference/meson.build b/docs/reference/meson.build
index 70e8d99f..4d329570 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-3-to-4.xml',
   'porting-guide-4-to-5.xml',
 ])
 
diff --git a/docs/reference/porting-guide-3-to-4.xml b/docs/reference/porting-guide-3-to-4.xml
deleted file mode 100644
index 8312edb7..00000000
--- a/docs/reference/porting-guide-3-to-4.xml
+++ /dev/null
@@ -1,175 +0,0 @@
-<?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-3-to-4">
-  <title>GtkSourceView 3 -> 4 Migration Guide</title>
-
-  <refsect1>
-    <title>GTK+ dependency</title>
-    <para>
-      Both GtkSourceView 3 and GtkSourceView 4 depend on GTK+ 3.
-    </para>
-  </refsect1>
-
-  <refsect1>
-    <title>Preparation in GtkSourceView 3</title>
-    <para>
-      GtkSourceView 3.24 is the latest stable GtkSourceView 3 version. Before
-      continuing this porting guide, you should use the 3.24 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>GtkSourceView 3.99.1</title>
-    <itemizedlist>
-      <listitem>
-        <para>
-          All the deprecated APIs have been removed.
-        </para>
-      </listitem>
-      <listitem>
-        <para>
-          Only <code>&lt;gtksourceview/gtksource.h&gt;</code> can be included
-          directly. There were already warnings about it in GtkSourceView 3. The
-          warnings have been changed to errors.
-        </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>
-
-  <refsect1>
-    <title>GtkSourceView 3.99.2</title>
-    <itemizedlist>
-      <listitem>
-        <para>
-          <code>gtk_source_completion_item_new2()</code> has been renamed to
-          <link linkend="gtk-source-completion-item-new">gtk_source_completion_item_new()</link>.
-        </para>
-      </listitem>
-      <listitem>
-        <para>
-          <code>gtk_source_search_context_forward2()</code> has been renamed to
-          <link linkend="gtk-source-search-context-forward">gtk_source_search_context_forward()</link>.
-        </para>
-      </listitem>
-      <listitem>
-        <para>
-          <code>gtk_source_search_context_forward_finish2()</code> has been renamed to
-          <link linkend="gtk-source-search-context-forward-finish">gtk_source_search_context_forward_finish()</link>.
-        </para>
-      </listitem>
-      <listitem>
-        <para>
-          <code>gtk_source_search_context_backward2()</code> has been renamed to
-          <link linkend="gtk-source-search-context-backward">gtk_source_search_context_backward()</link>.
-        </para>
-      </listitem>
-      <listitem>
-        <para>
-          <code>gtk_source_search_context_backward_finish2()</code> has been renamed to
-          <link linkend="gtk-source-search-context-backward-finish">gtk_source_search_context_backward_finish()</link>.
-        </para>
-      </listitem>
-      <listitem>
-        <para>
-          <code>gtk_source_search_context_replace2()</code> has been renamed to
-          <link linkend="gtk-source-search-context-replace">gtk_source_search_context_replace()</link>.
-        </para>
-      </listitem>
-      <listitem>
-        <para>
-          The <link linkend="GtkSourceSearchContext--settings">GtkSourceSearchContext:settings</link>
-          property is now construct-only.
-        </para>
-      </listitem>
-    </itemizedlist>
-  </refsect1>
-
-  <refsect1>
-    <title>GtkSourceView 3.99.3</title>
-    <para>No API changes.</para>
-  </refsect1>
-
-  <refsect1>
-    <title>GtkSourceView 3.99.4</title>
-    <itemizedlist>
-      <listitem>
-        <para>
-          The API of the
-          <link linkend="GtkSourceView-move-lines">GtkSourceView::move-lines</link>
-          keybinding signal has been simplified: the <code>copy</code> parameter
-          was deprecated and has been removed; and the <code>count</code>
-          parameter has been replaced by the <code>down</code> boolean.
-        </para>
-      </listitem>
-    </itemizedlist>
-  </refsect1>
-
-  <refsect1>
-    <title>GtkSourceView 3.99.5 and 3.99.6</title>
-    <para>No API changes.</para>
-  </refsect1>
-
-  <refsect1>
-    <title>GtkSourceView 3.99.7</title>
-    <para>
-      In order to have a better *.gir file and have less metadata to generate
-      the *.vapi for Vala, the following change has been made:
-    </para>
-    <itemizedlist>
-      <listitem>
-        <para>
-          <code>gtk_source_completion_show()</code> has been renamed to
-          <link linkend="gtk-source-completion-start">gtk_source_completion_start()</link>.
-          The function conflicted with the
-          <link linkend="GtkSourceCompletion-show">GtkSourceCompletion::show</link> signal.
-          Note that in Vala this doesn't require code changes because the method
-          was already renamed to <code>start()</code> in GtkSourceView&nbsp;3.
-        </para>
-      </listitem>
-    </itemizedlist>
-
-    <para>
-      Other changes in 3.99.7:
-    </para>
-    <itemizedlist>
-      <listitem>
-        <para>
-          For i18n initialization, the
-          <link linkend="gtk-source-init">gtk_source_init()</link> function
-          now needs to be called. There is also the
-          <link linkend="gtk-source-finalize">gtk_source_finalize()</link>
-          function which is convenient when using memory debugging tools.
-        </para>
-      </listitem>
-    </itemizedlist>
-  </refsect1>
-</chapter>