Additions.

3 files changed, 65 insertions, 14 deletions

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 2c06f57bb..3eb5fcda3 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,5 +1,8 @@
 2003-09-02  Matthias Clasen  <maclas@gmx.de>
 
+	* gtk/tmpl/gtkactiongroup.sgml: 
+	* gtk/tmpl/gtkuimanager.sgml: Additions.
+
 	* gtk/gtk-sections.txt: Add gtk_ui_manager_new_merge_id and
 	gtk_ui_manager_add_ui.
 
diff --git a/docs/reference/gtk/tmpl/gtkactiongroup.sgml b/docs/reference/gtk/tmpl/gtkactiongroup.sgml
index 04addcf0d..da03365b6 100644
--- a/docs/reference/gtk/tmpl/gtkactiongroup.sgml
+++ b/docs/reference/gtk/tmpl/gtkactiongroup.sgml
@@ -15,10 +15,18 @@ should be in a single group.  Multiple action groups may be used for a
 particular user interface.  In fact, it is expected that most nontrivial 
 applications will make use of multiple groups.  For example, in an application
 that can edit multiple documents, one group holding global actions 
-(eg. quit, about, new), and one group per document holding actions that 
+(e.g. quit, about, new), and one group per document holding actions that 
 act on that document (eg. save, cut/copy/paste, etc).  Each window's menus 
 would be constructed from a combination of two action groups.
 </para>
+<para>
+Accelerators are handled by the GTK+ accelerator map. All actions are 
+assigned an accelerator path of the form
+<literal>&lt;Actions&gt;/<replaceable>group-name</replaceable>/<replaceable>action-name</replaceable></literal> when they are added to an action group,
+and a shortcut is associated with this accelerator path. All menuitems and 
+toolitems take on this accelerator path. The GTK+ accelerator map code makes 
+sure that the correct shortcut is displayed next to the menu item.
+</para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
@@ -27,8 +35,8 @@ would be constructed from a combination of two action groups.
 
 <!-- ##### STRUCT GtkActionGroup ##### -->
 <para>
-The <structname>GtkActionGroup</structname> struct contains only private members
-and should not be accessed directly.
+The <structname>GtkActionGroup</structname> struct contains only private 
+members and should not be accessed directly.
 </para>
 
 
@@ -44,10 +52,11 @@ gtk_action_group_add_actions() to construct actions.
     translation, see gtk_action_group_set_translation_domain().
 @accelerator: The accelerator for the action, in the format understood by 
     gtk_accelerator_parse().
-@tooltip: The tooltip for the action. This field should typically be marked for 
-    translation, see gtk_action_group_set_translation_domain().
+@tooltip: The tooltip for the action. This field should typically be marked 
+    for translation, see gtk_action_group_set_translation_domain().
 @callback: The function to call when the action is activated.
-@is_toggle: If this is %TRUE, a #GtkToggleAction is constructed, else a #GtkAction.
+@is_toggle: If this is %TRUE, a #GtkToggleAction is constructed, else a 
+    #GtkAction.
 
 <!-- ##### STRUCT GtkRadioActionEntry ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkuimanager.sgml b/docs/reference/gtk/tmpl/gtkuimanager.sgml
index dbcf7fb56..5d845fea1 100644
--- a/docs/reference/gtk/tmpl/gtkuimanager.sgml
+++ b/docs/reference/gtk/tmpl/gtkuimanager.sgml
@@ -7,13 +7,13 @@ 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 ore 
-action groups.
+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 a #GMarkup format which can be
-roughly described by the following XML DTD.
+The UI definitions are specified in an XML format which can be
+roughly described by the following DTD. 
 <programlisting>
 &lt;!ELEMENT ui          (menubar|toolbar|popup)* &gt;
 &lt;!ELEMENT menubar     (menuitem|separator|placeholder|menu)* &gt;
@@ -40,9 +40,11 @@ roughly described by the following XML DTD.
 </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. If a name 
-is not specified, it defaults to the action. If an action is not specified 
-either, the element name is used.  
+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. If a name is not specified, it defaults 
+to the action. If an action is not specified either, the element name is 
+used.  
 </para>
 <example>
 <title>A UI definition</title>
@@ -111,6 +113,21 @@ 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 name 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>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
@@ -119,7 +136,8 @@ wrt. to its siblings in the partially constructed tree. If it is
 
 <!-- ##### STRUCT GtkUIManager ##### -->
 <para>
-
+The <structname>GtkUIManager</structname> struct contains only private
+members and should not be accessed directly.
 </para>
 
 
@@ -229,6 +247,27 @@ wrt. to its siblings in the partially constructed tree. If it is
 @Returns: 
 
 
+<!-- ##### FUNCTION gtk_ui_manager_new_merge_id ##### -->
+<para>
+
+</para>
+
+@self: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gtk_ui_manager_add_ui ##### -->
+<para>
+
+</para>
+
+@self: 
+@merge_id: 
+@path: 
+@name: 
+@action: 
+
+
 <!-- ##### FUNCTION gtk_ui_manager_remove_ui ##### -->
 <para>