[tepl] Amtk docs: add intro

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

commit 387ca37494c8a51e67ee1110bbf5ff371f7a76c8
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Tue Jul 18 12:13:11 2017 +0200

    Amtk docs: add intro

 amtk/amtk-action-info.c         |   10 +----
 docs/reference/Makefile.am      |    1 +
 docs/reference/amtk-intro.xml   |   86 +++++++++++++++++++++++++++++++++++++++
 docs/reference/tepl-docs.xml.in |    3 +-
 4 files changed, 91 insertions(+), 9 deletions(-)
---
diff --git a/amtk/amtk-action-info.c b/amtk/amtk-action-info.c
index fd61736..a6916b7 100644
--- a/amtk/amtk-action-info.c
+++ b/amtk/amtk-action-info.c
@@ -32,14 +32,8 @@
  * Those pieces of information are useful to create UI elements that trigger the
  * #GAction, for example a menu item or a toolbar item.
  *
- * When writing an XML file to create a #GMenu, with the format understood by
- * #GtkBuilder (see the class description of #GtkApplicationWindow), the
- * information in the XML file can be used only to create a #GMenu, not a
- * toolbar. The initial goal with #AmtkActionInfo and its related classes is to
- * encode the information just once, and be able to create both a menu and a
- * toolbar easily (to have a traditional user interface, not based on
- * #GtkHeaderBar). Note that with the Amtk API, it would also be possible to
- * create a #GMenu.
+ * The recommended way to create a set of #AmtkActionInfo's is to use the
+ * amtk_action_info_store_add_entries() function.
  */
 
 struct _AmtkActionInfo
diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
index 5ca51ba..2ea6015 100644
--- a/docs/reference/Makefile.am
+++ b/docs/reference/Makefile.am
@@ -42,6 +42,7 @@ HTML_IMAGES =
 
 # Extra XML files that are included by $(DOC_MAIN_SGML_FILE)
 content_files =                        \
+       amtk-intro.xml          \
        api-breaks.xml          \
        intro.xml
 
diff --git a/docs/reference/amtk-intro.xml b/docs/reference/amtk-intro.xml
new file mode 100644
index 0000000..82ac5ae
--- /dev/null
+++ b/docs/reference/amtk-intro.xml
@@ -0,0 +1,86 @@
+<?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="amtk-intro">
+<refmeta>
+  <refentrytitle>Amtk introduction</refentrytitle>
+</refmeta>
+
+<refnamediv>
+  <refname>Amtk introduction</refname>
+  <refpurpose>
+    Introduction to the Actions, Menus and Toolbars Kit for GTK+
+  </refpurpose>
+</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>.
+  <link linkend="GtkUIManager">GtkUIManager</link> has been deprecated in
+  GTK+&nbsp;3, without a good enough 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”).
+</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.
+</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> classes 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>
+</itemizedlist>
+</refentry>
diff --git a/docs/reference/tepl-docs.xml.in b/docs/reference/tepl-docs.xml.in
index 9009483..958d883 100644
--- a/docs/reference/tepl-docs.xml.in
+++ b/docs/reference/tepl-docs.xml.in
@@ -18,7 +18,8 @@
     <title>Amtk API Reference</title>
 
     <chapter id="amtk">
-      <title>Actions, Menus and Toolbars Kit</title>
+      <title>Actions, Menus and Toolbars Kit for GTK+</title>
+      <xi:include href="amtk-intro.xml"/>
       <xi:include href="xml/amtk-application-window.xml"/>
       <xi:include href="xml/amtk-action-info.xml"/>
       <xi:include href="xml/amtk-action-info-store.xml"/>