[amtk] docs: write gradual-porting page

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

commit 4d5eb3f7d7e9c66d44cdf011b923e5e7c15f9ebf
Author: Sébastien Wilmet <swilmet informatique-libre be>
Date:   Fri May 6 14:02:03 2022 +0200

    docs: write gradual-porting page

 docs/reference/amtk-docs.xml       |  1 +
 docs/reference/gradual-porting.xml | 59 ++++++++++++++++++++++++++++++++++++++
 docs/reference/meson.build         |  1 +
 3 files changed, 61 insertions(+)
---
diff --git a/docs/reference/amtk-docs.xml b/docs/reference/amtk-docs.xml
index faf7493..3e2033b 100644
--- a/docs/reference/amtk-docs.xml
+++ b/docs/reference/amtk-docs.xml
@@ -13,6 +13,7 @@
   </bookinfo>
 
   <xi:include href="amtk-intro.xml"/>
+  <xi:include href="gradual-porting.xml"/>
 
   <part id="api-reference">
     <title>Amtk API Reference</title>
diff --git a/docs/reference/gradual-porting.xml b/docs/reference/gradual-porting.xml
new file mode 100644
index 0000000..dd979f1
--- /dev/null
+++ b/docs/reference/gradual-porting.xml
@@ -0,0 +1,59 @@
+<?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;
+]>
+
+<refentry id="gradual-porting">
+<refmeta>
+  <refentrytitle>Gradual Porting</refentrytitle>
+</refmeta>
+
+<refnamediv>
+  <refname>Gradual Porting</refname>
+  <refpurpose>
+    Gradually porting away from <link linkend="GtkAction">GtkAction</link> and
+    <link linkend="GtkUIManager">GtkUIManager</link>.
+  </refpurpose>
+</refnamediv>
+
+<para>
+  Even if you don't want to use Amtk in the end, Amtk can help to gradually move
+  away from <link linkend="GtkAction">GtkAction</link> and
+  <link linkend="GtkUIManager">GtkUIManager</link>.
+</para>
+
+<refsect1>
+  <title>Moving gradually to <link linkend="GAction">GAction</link></title>
+  <para>
+    Amtk provides the following functions that can help:
+  </para>
+  <itemizedlist>
+    <listitem>
+      <para>
+        <link 
linkend="amtk-utils-bind-g-action-to-gtk-action">amtk_utils_bind_g_action_to_gtk_action()</link>
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        <link linkend="amtk-utils-create-gtk-action">amtk_utils_create_gtk_action()</link>
+      </para>
+    </listitem>
+  </itemizedlist>
+</refsect1>
+
+<refsect1>
+  <title>Moving gradually away from <link linkend="GtkUIManager">GtkUIManager</link></title>
+  <para>
+    For example if you have already ported a submenu, but not the whole menu,
+    you can use the
+    <link linkend="gtk-ui-manager-get-widget">gtk_ui_manager_get_widget()</link>
+    function to get a <link linkend="GtkMenuItem">GtkMenuItem</link>, and then
+    set the submenu with
+    <link linkend="gtk-menu-item-set-submenu">gtk_menu_item_set_submenu()</link>.
+  </para>
+</refsect1>
+</refentry>
diff --git a/docs/reference/meson.build b/docs/reference/meson.build
index 1db1efb..1728479 100644
--- a/docs/reference/meson.build
+++ b/docs/reference/meson.build
@@ -30,6 +30,7 @@ GNOME.gtkdoc(
   ],
   content_files: [
     'amtk-intro.xml',
+    'gradual-porting.xml',
   ],
   install: true
 )