[amtk] docs: update intro

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

commit 0f654f04d0bbce302cb4be4d5464e1c21369a958
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Sat Apr 14 18:15:27 2018 +0200

    docs: update intro

 docs/reference/amtk-intro.xml.in |  152 ++++++++++++++++++++++----------------
 1 files changed, 87 insertions(+), 65 deletions(-)
---
diff --git a/docs/reference/amtk-intro.xml.in b/docs/reference/amtk-intro.xml.in
index 0fe815b..056b702 100644
--- a/docs/reference/amtk-intro.xml.in
+++ b/docs/reference/amtk-intro.xml.in
@@ -20,78 +20,100 @@
 </refnamediv>
 
 <para>
-  Amtk is the acronym for “Actions, Menus and Toolbars Kit”. It is a basic
-  <link linkend="GtkUIManager">GtkUIManager</link> replacement based on
-  <link linkend="GAction">GAction</link>.
+  Amtk is the acronym for “Actions, Menus and Toolbars Kit”. Amtk has been
+  initially created as a basic <link linkend="GtkUIManager">GtkUIManager</link>
+  replacement based on <link linkend="GAction">GAction</link>.
   <link linkend="GtkUIManager">GtkUIManager</link> has been deprecated in
-  GTK+&nbsp;3, without a good replacement for applications that want to keep a
-  traditional UI (with a <link linkend="GtkMenuBar">GtkMenuBar</link>, a
+  GTK+&nbsp;3 (and removed in GTK+&nbsp;4), without a good replacement for
+  applications that want to keep a traditional UI (with a
+  <link linkend="GtkMenuBar">GtkMenuBar</link>, a
   <link linkend="GtkToolbar">GtkToolbar</link> and a
-  <link linkend="GtkStatusbar">GtkStatusbar</link>; in contrast to the new UI
-  with a <link linkend="GtkHeaderBar">GtkHeaderBar</link> and a “hamburger
-  menu”).
+  <link linkend="GtkStatusbar">GtkStatusbar</link>). Amtk is now suitable for
+  both a traditional UI and for a new UI with a
+  <link linkend="GtkHeaderBar">GtkHeaderBar</link> and a “hamburger menu”.
 </para>
 
 <para>
-  With Amtk, menus and toolbars are created programmatically, but with
-  convenient APIs (the support for an XML format will maybe be added in the
-  future, contributions welcome). <link linkend="GMenu">GMenu</link> is not
-  used, a menubar is created with <link linkend="GtkMenuItem">GtkMenuItem</link>'s,
-  although the support for <link linkend="GMenu">GMenu</link> could easily be
-  added.
+  With Amtk, menus, toolbars or other objects like
+  <link linkend="GtkShortcutsWindow">GtkShortcutsWindow</link> are created
+  programmatically (not with a *.ui file), but with convenient APIs. The support
+  for an XML format will maybe be added in the future, contributions welcome.
 </para>
 
-<para>
-  There are currently several things that are not possible to do with the
-  support of <link linkend="GMenu">GMenu</link> in GTK+, that Amtk solves:
-</para>
-<itemizedlist>
-  <listitem>
-    <para>
-      Primarily, encoding the information about an action only once, to create
-      both a menu item and a toolbar item for that action. The information
-      needed: a label (i.e. a short description), an icon, a tooltip (i.e. a
-      longer description) and keyboard shortcuts. This is implemented by
-      <link linkend="AmtkActionInfo">AmtkActionInfo</link>, with
-      <link linkend="AmtkFactory">AmtkFactory</link> functions to create menu
-      and toolbar items.
-    </para>
-    <para>
-      When writing an XML file to create a <link linkend="GMenu">GMenu</link>
-      with the format understood by <link linkend="GtkBuilder">GtkBuilder</link>
-      (see the class description of <link linkend="GtkApplicationWindow">GtkApplicationWindow</link>),
-      the information in the XML file can be used only to create a <link linkend="GMenu">GMenu</link>,
-      not a toolbar. It would not be convenient to duplicate the information.
-    </para>
-  </listitem>
-  <listitem>
-    <para>
-      When a <link linkend="GtkMenuItem">GtkMenuItem</link> is selected (e.g.
-      when the mouse hovers it), showing a longer description in the
-      <link linkend="GtkStatusbar">GtkStatusbar</link>. This is implemented by
-      <link linkend="AmtkApplicationWindow">AmtkApplicationWindow</link>. It
-      makes the UI better self-discoverable, to improve the usability.
-    </para>
-  </listitem>
-  <listitem>
-    <para>
-      Related to the previous point: having a
-      <link linkend="GtkRecentChooser">GtkRecentChooser</link> menu that shows
-      in a <link linkend="GtkStatusbar">GtkStatusbar</link> the full file path
-      when a menu item is selected. This is implemented by
-      <link 
linkend="amtk-application-window-connect-recent-chooser-menu-to-statusbar">amtk_application_window_connect_recent_chooser_menu_to_statusbar()</link>.
-    </para>
-  </listitem>
-  <listitem>
-    <para>
-      Additionally, the Amtk infrastructure permits to share
-      <link linkend="AmtkActionInfo">AmtkActionInfo</link>'s in a library (with
-      translations); this is a bit similar to
-      <link linkend="GtkStockItem">GtkStockItem</link>, to reduce the amount of
-      work that an application (and translators) need to do.
-    </para>
-  </listitem>
-</itemizedlist>
+<refsect1>
+  <title>General advantages</title>
+  <itemizedlist>
+    <listitem>
+      <para>
+        Primarily, encoding the information about an action only once, to create
+        various objects such as a menu item, a toolbar item, a
+        <link linkend="GtkShortcutsShortcut">GtkShortcutsShortcut</link>, etc.
+        The information needed about an action: a label (i.e. a short
+        description), possibly an icon, a tooltip (i.e. a longer description)
+        and keyboard shortcuts. This is implemented by
+        <link linkend="AmtkActionInfo">AmtkActionInfo</link>, with
+        <link linkend="AmtkFactory">AmtkFactory</link> functions to create
+        various objects.
+      </para>
+      <para>
+        This also has the nice benefit that all the information about an action
+        is centralized in only one place, to keep related information close
+        together. This permits to more easily catch inconsistencies.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Amtk has been designed to be able to share
+        <link linkend="AmtkActionInfo">AmtkActionInfo</link>'s in a library (with
+        translations); this is a bit similar to
+        <link linkend="GtkStockItem">GtkStockItem</link>, to reduce the amount of
+        work that an application (and translators) need to do. As a result the
+        library can provide a higher-level API.
+      </para>
+    </listitem>
+  </itemizedlist>
+</refsect1>
+
+<refsect1>
+  <title>Advantages for a traditional UI</title>
+  <itemizedlist>
+    <listitem>
+      <para>
+        When writing an XML file to create a <link linkend="GMenu">GMenu</link>
+        with the format understood by <link linkend="GtkBuilder">GtkBuilder</link>
+        (see the class description of <link linkend="GtkApplicationWindow">GtkApplicationWindow</link>),
+        the information in the XML file can be used only to create a <link linkend="GMenu">GMenu</link>,
+        not a toolbar. It is not a good programming practice to duplicate the
+        information. With Amtk the information is encoded just once, in
+        <link linkend="AmtkActionInfo">AmtkActionInfo</link>'s, and menu and
+        toolbar items are created with <link linkend="AmtkFactory">AmtkFactory</link>
+        which uses the information provided by the
+        <link linkend="AmtkActionInfo">AmtkActionInfo</link>'s.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Something that is not possible to do with the support of
+        <link linkend="GMenu">GMenu</link> in GTK+, that Amtk solves when using
+        <link linkend="GtkMenuItem">GtkMenuItem</link>'s: when a
+        <link linkend="GtkMenuItem">GtkMenuItem</link> is selected (e.g. when
+        the mouse hovers it), showing a longer description in the
+        <link linkend="GtkStatusbar">GtkStatusbar</link>. This is implemented by
+        <link linkend="AmtkApplicationWindow">AmtkApplicationWindow</link>. It
+        makes the UI better self-discoverable, to improve the usability.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Related to the previous point: having a
+        <link linkend="GtkRecentChooser">GtkRecentChooser</link> menu that shows
+        in a <link linkend="GtkStatusbar">GtkStatusbar</link> the full file path
+        when a menu item is selected. This is implemented by
+        <link 
linkend="amtk-application-window-connect-recent-chooser-menu-to-statusbar">amtk_application_window_connect_recent_chooser_menu_to_statusbar()</link>.
+      </para>
+    </listitem>
+  </itemizedlist>
+</refsect1>
 
 <refsect1>
   <title>Sanity checks</title>