Move documentation to inline comments: GtkUIManager

2 files changed, 1 insertions, 508 deletions

diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore
index 997eb9e0f6..ac14a49130 100644
--- a/docs/reference/gtk/tmpl/.gitignore
+++ b/docs/reference/gtk/tmpl/.gitignore
@@ -140,5 +140,6 @@ gtktreestore.sgml
 gtktreeview.sgml
 gtktreeviewcolumn.sgml
 gtktypeutils.sgml
+gtkuimanager.sgml
 gtkwindow.sgml
 gtkwindowgroup.sgml
diff --git a/docs/reference/gtk/tmpl/gtkuimanager.sgml b/docs/reference/gtk/tmpl/gtkuimanager.sgml
deleted file mode 100644
index 721e444b89..0000000000
--- a/docs/reference/gtk/tmpl/gtkuimanager.sgml
+++ /dev/null
@@ -1,508 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-GtkUIManager
-
-<!-- ##### SECTION Short_Description ##### -->
-Constructing menus and toolbars from an XML description
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-A #GtkUIManager constructs a user interface (menus and toolbars) from
-one or more UI definitions, which reference actions from one or more 
-action groups. 
-</para>
-<refsect2 id="XML-UI"><title>UI Definitions</title>
-<para>
-The UI definitions are specified in an XML format which can be
-roughly described by the following DTD. 
-</para>
-<para>
-Do not confuse the GtkUIManager UI Definitions described here with
-the similarly named <link linkend="BUILDER-UI">GtkBuilder UI 
-Definitions</link>. 
-</para>
-<para>
-<programlisting><![CDATA[
-<!ELEMENT ui          (menubar|toolbar|popup|accelerator)* >
-<!ELEMENT menubar     (menuitem|separator|placeholder|menu)* >
-<!ELEMENT menu        (menuitem|separator|placeholder|menu)* >
-<!ELEMENT popup       (menuitem|separator|placeholder|menu)* >
-<!ELEMENT toolbar     (toolitem|separator|placeholder)* >
-<!ELEMENT placeholder (menuitem|toolitem|separator|placeholder|menu)* >
-<!ELEMENT menuitem     EMPTY >
-<!ELEMENT toolitem     (menu?) >
-<!ELEMENT separator    EMPTY >
-<!ELEMENT accelerator  EMPTY >
-<!ATTLIST menubar      name                      &num;IMPLIED 
-                       action                    &num;IMPLIED >
-<!ATTLIST toolbar      name                      &num;IMPLIED 
-                       action                    &num;IMPLIED >
-<!ATTLIST popup        name                      &num;IMPLIED 
-                       action                    &num;IMPLIED 
-                       accelerators (true|false) &num;IMPLIED >
-<!ATTLIST placeholder  name                      &num;IMPLIED
-                       action                    &num;IMPLIED >
-<!ATTLIST separator    name                      &num;IMPLIED
-                       action                    &num;IMPLIED
-                       expand       (true|false) &num;IMPLIED >
-<!ATTLIST menu         name                      &num;IMPLIED
-                       action                    &num;REQUIRED
-                       position     (top|bot)    &num;IMPLIED >
-<!ATTLIST menuitem     name                      &num;IMPLIED
-                       action                    &num;REQUIRED
-                       position     (top|bot)    &num;IMPLIED
-                       always-show-image (true|false) &num;IMPLIED >
-<!ATTLIST toolitem     name                      &num;IMPLIED
-                       action                    &num;REQUIRED
-                       position     (top|bot)    &num;IMPLIED >
-<!ATTLIST accelerator  name                      &num;IMPLIED
-                       action                    &num;REQUIRED >
-]]></programlisting>
-There are some additional restrictions beyond those specified in the
-DTD, e.g. every toolitem must have a toolbar in its anchestry and
-every menuitem must have a menubar or popup in its anchestry. Since
-a #GMarkup parser is used to parse the UI description, it must not only
-be valid XML, but valid #GMarkup. 
-</para>
-<para>
-If a name is not specified, it defaults to the action. If an action is 
-not specified either, the element name is used. The name and action 
-attributes must not contain '/' characters after parsing (since that 
-would mess up path lookup) and must be usable as XML attributes when 
-enclosed in doublequotes, thus they must not '"' characters or references 
-to the &amp;quot; entity.
-</para>
-<example>
-<title>A UI definition</title>
-<programlisting>
-&lt;ui&gt;
-  &lt;menubar&gt;
-    &lt;menu name="FileMenu" action="FileMenuAction"&gt;
-      &lt;menuitem name="New" action="New2Action" /&gt;
-      &lt;placeholder name="FileMenuAdditions" /&gt;
-    &lt;/menu&gt;
-    &lt;menu name="JustifyMenu" action="JustifyMenuAction"&gt;
-      &lt;menuitem name="Left" action="justify-left"/&gt;
-      &lt;menuitem name="Centre" action="justify-center"/&gt;
-      &lt;menuitem name="Right" action="justify-right"/&gt;
-      &lt;menuitem name="Fill" action="justify-fill"/&gt;
-    &lt;/menu&gt;
-  &lt;/menubar&gt;
-  &lt;toolbar action="toolbar1"&gt;
-    &lt;placeholder name="JustifyToolItems"&gt;
-      &lt;separator/&gt;
-      &lt;toolitem name="Left" action="justify-left"/&gt;
-      &lt;toolitem name="Centre" action="justify-center"/&gt;
-      &lt;toolitem name="Right" action="justify-right"/&gt;
-      &lt;toolitem name="Fill" action="justify-fill"/&gt;
-      &lt;separator/&gt;
-    &lt;/placeholder&gt;
-  &lt;/toolbar&gt;
-&lt;/ui&gt;
-</programlisting>
-</example>
-<para>
-The constructed widget hierarchy is very similar to the element tree
-of the XML, with the exception that placeholders are merged into their
-parents. The correspondence of XML elements to widgets should be
-almost obvious: 
-<variablelist>
-<varlistentry><term>menubar</term>
-<listitem><para>a #GtkMenuBar</para></listitem>
-</varlistentry>
-<varlistentry><term>toolbar</term>
-<listitem><para>a #GtkToolbar</para></listitem>
-</varlistentry>
-<varlistentry><term>popup</term>
-<listitem><para>a toplevel #GtkMenu</para></listitem>
-</varlistentry>
-<varlistentry><term>menu</term>
-<listitem><para>a #GtkMenu attached to a menuitem</para></listitem>
-</varlistentry>
-<varlistentry><term>menuitem</term>
-<listitem><para>a #GtkMenuItem subclass, the exact type depends on the
-action</para></listitem> 
-</varlistentry>
-<varlistentry><term>toolitem</term>
-<listitem><para>a #GtkToolItem subclass, the exact type depends on the
-action. Note that toolitem elements may contain a menu element, but only
-if their associated action specifies a #GtkMenuToolButton as proxy.</para></listitem> 
-</varlistentry>
-<varlistentry><term>separator</term>
-<listitem><para>a #GtkSeparatorMenuItem or
-#GtkSeparatorToolItem</para></listitem> 
-</varlistentry>
-<varlistentry><term>accelerator</term>
-<listitem><para>a keyboard accelerator</para></listitem> 
-</varlistentry>
-</variablelist>
-</para>
-<para>
-The "position" attribute determines where a constructed widget is positioned
-wrt. to its siblings in the partially constructed tree. If it is
-"top", the widget is prepended, otherwise it is appended.
-</para>
-</refsect2>
-<refsect2 id="UI-Merging">
-<title>UI Merging</title>
-<para>
-The most remarkable feature of #GtkUIManager is that it can overlay a set
-of menuitems and toolitems over another one, and demerge them later.
-</para>
-<para>
-Merging is done based on the names of the XML elements. Each element is 
-identified by a path which consists of the names of its anchestors, separated
-by slashes. For example, the menuitem named "Left" in the example above
-has the path <literal>/ui/menubar/JustifyMenu/Left</literal> and the
-toolitem with the same name has path 
-<literal>/ui/toolbar1/JustifyToolItems/Left</literal>.
-</para>
-</refsect2>
-<refsect2>
-<title>Accelerators</title>
-<para>
-Every action has an accelerator path. Accelerators are installed together with
-menuitem proxies, but they can also be explicitly added with &lt;accelerator&gt;
-elements in the UI definition. This makes it possible to have accelerators for
-actions even if they have no visible proxies.
-</para>
-</refsect2>
-<refsect2 id="Smart-Separators">
-<title>Smart Separators</title>
-<para>
-The separators created by #GtkUIManager are "smart", i.e. they do not show up 
-in the UI unless they end up between two visible menu or tool items. Separators
-which are located at the very beginning or end of the menu or toolbar 
-containing them, or multiple separators next to each other, are hidden. This 
-is a useful feature, since the merging of UI elements from multiple sources 
-can make it hard or impossible to determine in advance whether a separator 
-will end up in such an unfortunate position.
-</para>
-
-<para>
-For separators in toolbars, you can set <literal>expand="true"</literal> to
-turn them from a small, visible separator to an expanding, invisible one.
-Toolitems following an expanding separator are effectively right-aligned.
-</para>
-</refsect2>
-<refsect2>
-<title>Empty Menus</title>
-<para>
-Submenus pose similar problems to separators inconnection with merging. It is 
-impossible to know in advance whether they will end up empty after merging. 
-#GtkUIManager offers two ways to treat empty submenus:
-<itemizedlist>
-<listitem><para>make them disappear by hiding the menu item they're attached to
-</para></listitem>
-<listitem><para>add an insensitive "Empty" item
-</para></listitem>
-</itemizedlist>
-The behaviour is chosen based on the "hide_if_empty" property of the action 
-to which the submenu is associated.
-</para>
-</refsect2>
-
-<refsect2 id="GtkUIManager-BUILDER-UI">
-<title>GtkUIManager as GtkBuildable</title>
-<para>
-The GtkUIManager implementation of the GtkBuildable interface accepts
-GtkActionGroup objects as &lt;child&gt; elements in UI definitions.
-</para>
-<para>
-A GtkUIManager UI definition as described above can be embedded in
-an GtkUIManager &lt;object&gt; element in a GtkBuilder UI definition.
-</para>
-<para>
-The widgets that are constructed by a GtkUIManager can be embedded in
-other parts of the constructed user interface with the help of the
-"constructor" attribute. See the example below.
-</para>
-<example>
-<title>An embedded GtkUIManager UI definition</title>
-<programlisting><![CDATA[
-<object class="GtkUIManager" id="uiman">
-  <child>
-    <object class="GtkActionGroup" id="actiongroup">
-      <child>
-        <object class="GtkAction" id="file">
-          <property name="label">_File</property>
-        </object>
-      </child>
-    </object>
-  </child>
-  <ui>
-    <menubar name="menubar1">
-      <menu action="file">
-      </menu>
-    </menubar>
-  </ui>
-</object>
-<object class="GtkWindow" id="main-window">
-  <child>
-    <object class="GtkMenuBar" id="menubar1" constructor="uiman"/>
-  </child>
-</object>
-]]></programlisting>
-</example>
-</refsect2>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-#GtkBuilder
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### SECTION Image ##### -->
-
-
-<!-- ##### STRUCT GtkUIManager ##### -->
-<para>
-The <structname>GtkUIManager</structname> struct contains only private
-members and should not be accessed directly.
-</para>
-
-
-<!-- ##### SIGNAL GtkUIManager::actions-changed ##### -->
-<para>
-
-</para>
-
-@uimanager: the object which received the signal.
-
-<!-- ##### SIGNAL GtkUIManager::add-widget ##### -->
-<para>
-
-</para>
-
-@uimanager: the object which received the signal.
-@widget: 
-
-<!-- ##### SIGNAL GtkUIManager::connect-proxy ##### -->
-<para>
-
-</para>
-
-@uimanager: the object which received the signal.
-@arg1: 
-@widget: 
-
-<!-- ##### SIGNAL GtkUIManager::disconnect-proxy ##### -->
-<para>
-
-</para>
-
-@uimanager: the object which received the signal.
-@arg1: 
-@widget: 
-
-<!-- ##### SIGNAL GtkUIManager::post-activate ##### -->
-<para>
-
-</para>
-
-@uimanager: the object which received the signal.
-@arg1: 
-
-<!-- ##### SIGNAL GtkUIManager::pre-activate ##### -->
-<para>
-
-</para>
-
-@uimanager: the object which received the signal.
-@arg1: 
-
-<!-- ##### ARG GtkUIManager:add-tearoffs ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkUIManager:ui ##### -->
-<para>
-
-</para>
-
-<!-- ##### FUNCTION gtk_ui_manager_new ##### -->
-<para>
-
-</para>
-
-@void: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_ui_manager_set_add_tearoffs ##### -->
-<para>
-
-</para>
-
-@manager: 
-@add_tearoffs: 
-
-
-<!-- ##### FUNCTION gtk_ui_manager_get_add_tearoffs ##### -->
-<para>
-
-</para>
-
-@manager: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_ui_manager_insert_action_group ##### -->
-<para>
-
-</para>
-
-@manager: 
-@action_group: 
-@pos: 
-
-
-<!-- ##### FUNCTION gtk_ui_manager_remove_action_group ##### -->
-<para>
-
-</para>
-
-@manager: 
-@action_group: 
-
-
-<!-- ##### FUNCTION gtk_ui_manager_get_action_groups ##### -->
-<para>
-
-</para>
-
-@manager: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_ui_manager_get_accel_group ##### -->
-<para>
-
-</para>
-
-@manager: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_ui_manager_get_widget ##### -->
-<para>
-
-</para>
-
-@manager: 
-@path: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_ui_manager_get_toplevels ##### -->
-<para>
-
-</para>
-
-@manager: 
-@types: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_ui_manager_get_action ##### -->
-<para>
-
-</para>
-
-@manager: 
-@path: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_ui_manager_add_ui_from_string ##### -->
-<para>
-
-</para>
-
-@manager: 
-@buffer: 
-@length: 
-@error: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_ui_manager_add_ui_from_file ##### -->
-<para>
-
-</para>
-
-@manager: 
-@filename: 
-@error: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_ui_manager_new_merge_id ##### -->
-<para>
-
-</para>
-
-@manager: 
-@Returns: 
-
-
-<!-- ##### ENUM GtkUIManagerItemType ##### -->
-<para>
-These enumeration values are used by gtk_ui_manager_add_ui() to determine
-what UI element to create.
-</para>
-
-@GTK_UI_MANAGER_AUTO: Pick the type of the UI element according to context.
-@GTK_UI_MANAGER_MENUBAR: Create a menubar.
-@GTK_UI_MANAGER_MENU: Create a menu.
-@GTK_UI_MANAGER_TOOLBAR: Create a toolbar.
-@GTK_UI_MANAGER_PLACEHOLDER: Insert a placeholder.
-@GTK_UI_MANAGER_POPUP: Create a popup menu.
-@GTK_UI_MANAGER_MENUITEM: Create a menuitem.
-@GTK_UI_MANAGER_TOOLITEM: Create a toolitem.
-@GTK_UI_MANAGER_SEPARATOR: Create a separator.
-@GTK_UI_MANAGER_ACCELERATOR: Install an accelerator.
-@GTK_UI_MANAGER_POPUP_WITH_ACCELS: Same as %GTK_UI_MANAGER_POPUP, but the actions' accelerators are shown.
-
-<!-- ##### FUNCTION gtk_ui_manager_add_ui ##### -->
-<para>
-
-</para>
-
-@manager: 
-@merge_id: 
-@path: 
-@name: 
-@action: 
-@type: 
-@top: 
-
-
-<!-- ##### FUNCTION gtk_ui_manager_remove_ui ##### -->
-<para>
-
-</para>
-
-@manager: 
-@merge_id: 
-
-
-<!-- ##### FUNCTION gtk_ui_manager_get_ui ##### -->
-<para>
-
-</para>
-
-@manager: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_ui_manager_ensure_update ##### -->
-<para>
-
-</para>
-
-@manager: 
-
-