docs: Use markdown for section headings

6 files changed, 49 insertions, 69 deletions

diff --git a/gtk/deprecated/gtkactiongroup.c b/gtk/deprecated/gtkactiongroup.c
index 9a2c9afdc4..b99644992a 100644
--- a/gtk/deprecated/gtkactiongroup.c
+++ b/gtk/deprecated/gtkactiongroup.c
@@ -44,7 +44,8 @@
  * window's menus would be constructed from a combination of two action
  * groups.
  *
- * <para id="Action-Accel">
+ * ## Accelerators ## {#Action-Accel}
+ *
  * Accelerators are handled by the GTK+ accelerator map. All actions are
  * assigned an accelerator path (which normally has the form
  * <literal>&lt;Actions&gt;/group-name/action-name</literal>)
@@ -52,11 +53,9 @@
  * 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>
  *
- * <refsect2 id="GtkActionGroup-BUILDER-UI">
- * <title>GtkActionGroup as GtkBuildable</title>
- * <para>
+ * # GtkActionGroup as GtkBuildable # {#GtkActionGroup-BUILDER-UI}
+ *
  * The #GtkActionGroup implementation of the #GtkBuildable interface accepts
  * #GtkAction objects as &lt;child&gt; elements in UI definitions.
  *
@@ -68,9 +67,8 @@
  * modifiers and allows to specify accelerators. This is similar to the
  * &lt;accelerator&gt; element of #GtkWidget, the main difference is that
  * it doesn't allow you to specify a signal.
- * </para>
- * <example>
- * <title>A #GtkDialog UI definition fragment.</title>
+ *
+ * ## A #GtkDialog UI definition fragment. ##
  * |[
  * <object class="GtkActionGroup" id="actiongroup">
  *   <child>
@@ -83,8 +81,7 @@
  *   </child>
  * </object>
  * ]|
- * </example>
- * </refsect2>
+ *
  */
 
 #include "config.h"
diff --git a/gtk/deprecated/gtkactivatable.c b/gtk/deprecated/gtkactivatable.c
index c14a7242e3..3a0b8cbd39 100644
--- a/gtk/deprecated/gtkactivatable.c
+++ b/gtk/deprecated/gtkactivatable.c
@@ -25,9 +25,8 @@
  * through its action, as they are responsible for activating their
  * related actions.
  *
- * <refsect2>
- * <title>Implementing GtkActivatable</title>
- * <para>
+ * # Implementing GtkActivatable
+ *
  * When extending a class that is already #GtkActivatable; it is only
  * necessary to implement the #GtkActivatable->sync_action_properties()
  * and #GtkActivatable->update() methods and chain up to the parent
@@ -38,9 +37,9 @@
  * the action pointer and boolean flag on your instance, and calling
  * gtk_activatable_do_set_related_action() and
  * gtk_activatable_sync_action_properties() at the appropriate times.
- * </para>
- * <example>
- * <title>A class fragment implementing #GtkActivatable</title>
+ *
+ * ## A class fragment implementing #GtkActivatable
+ *
  * |[<!-- language="C" -->
  *
  * enum {
@@ -253,9 +252,8 @@
  *     foo_bar_set_label (button, gtk_action_get_label (action));
  * 
  *   ...
- * }]|
- * </example>
- * </refsect2>
+ * }
+ * ]|
  */
 
 #include "config.h"
diff --git a/gtk/deprecated/gtkcolorseldialog.c b/gtk/deprecated/gtkcolorseldialog.c
index 87408f7745..b5cd48d6cb 100644
--- a/gtk/deprecated/gtkcolorseldialog.c
+++ b/gtk/deprecated/gtkcolorseldialog.c
@@ -51,13 +51,12 @@
  * for this widget's #GtkColorSelection::color-changed signal to be notified
  * when the color changes.
  *
- * <refsect2 id="GtkColorSelectionDialog-BUILDER-UI">
- * <title>GtkColorSelectionDialog as GtkBuildable</title>
+ * # GtkColorSelectionDialog as GtkBuildable # {#GtkColorSelectionDialog-BUILDER-UI}
+ *
  * The GtkColorSelectionDialog implementation of the GtkBuildable interface
  * exposes the embedded #GtkColorSelection as internal child with the
  * name "color_selection". It also exposes the buttons with the names
  * "ok_button", "cancel_button" and "help_button".
- * </refsect2>
  */
 
 
diff --git a/gtk/deprecated/gtkfontsel.c b/gtk/deprecated/gtkfontsel.c
index 9440c422ce..0ac6561836 100644
--- a/gtk/deprecated/gtkfontsel.c
+++ b/gtk/deprecated/gtkfontsel.c
@@ -1626,13 +1626,12 @@ gtk_font_selection_set_preview_text  (GtkFontSelection *fontsel,
  * In GTK+ 3.2, #GtkFontSelectionDialog has been deprecated in favor of
  * #GtkFontChooserDialog.
  *
- * <refsect2 id="GtkFontSelectionDialog-BUILDER-UI">
- * <title>GtkFontSelectionDialog as GtkBuildable</title>
+ * # GtkFontSelectionDialog as GtkBuildable # {#GtkFontSelectionDialog-BUILDER-UI}
+ *
  * The GtkFontSelectionDialog implementation of the GtkBuildable interface
  * exposes the embedded #GtkFontSelection as internal child with the
  * name "font_selection". It also exposes the buttons with the names
  * "ok_button", "cancel_button" and "apply_button".
- * </refsect2>
  */
 
 static void gtk_font_selection_dialog_buildable_interface_init     (GtkBuildableIface *iface);
diff --git a/gtk/deprecated/gtkiconfactory.c b/gtk/deprecated/gtkiconfactory.c
index accf8f1543..a5c2c892e5 100644
--- a/gtk/deprecated/gtkiconfactory.c
+++ b/gtk/deprecated/gtkiconfactory.c
@@ -70,12 +70,12 @@
  * gtk_widget_render_icon(). These functions take the theme into account when
  * looking up the icon to use for a given stock ID.
  *
- * <refsect2 id="GtkIconFactory-BUILDER-UI">
- * <title>GtkIconFactory as GtkBuildable</title>
- * <para>
+ * # GtkIconFactory as GtkBuildable # {#GtkIconFactory-BUILDER-UI}
+ *
  * GtkIconFactory supports a custom &lt;sources&gt; element, which can contain
  * multiple &lt;source&gt; elements.
  * The following attributes are allowed:
+ *
  * <variablelist>
  * <varlistentry>
  * <term>stock-id</term>
@@ -120,8 +120,9 @@
  * </para></listitem>
  * </varlistentry>
  * </variablelist>
- * <example>
- * <title>A #GtkIconFactory UI definition fragment.</title>
+ *
+ * ## A #GtkIconFactory UI definition fragment. ##
+ *
  * |[
  * <object class="GtkIconFactory" id="iconfactory1">
  *   <sources>
@@ -137,9 +138,6 @@
  *   </child>
  * </object>
  * ]|
- * </example>
- * </para>
- * </refsect2>
  */
 
 
diff --git a/gtk/deprecated/gtkuimanager.c b/gtk/deprecated/gtkuimanager.c
index 0b8df582b1..ddc844a192 100644
--- a/gtk/deprecated/gtkuimanager.c
+++ b/gtk/deprecated/gtkuimanager.c
@@ -60,9 +60,8 @@
  * one or more UI definitions, which reference actions from one or more
  * action groups.
  *
- * <refsect2 id="XML-UI">
- * <title>UI Definitions</title>
- * <para>
+ * # UI Definitions # {#XML-UI}
+ *
  * The UI definitions are specified in an XML format which can be
  * roughly described by the following DTD.
  *
@@ -108,6 +107,7 @@
  * <!ATTLIST accelerator  name                      #IMPLIED
  *                        action                    #REQUIRED >
  * ]|
+ *
  * 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
@@ -121,8 +121,8 @@
  * enclosed in doublequotes, thus they must not '"' characters or references
  * to the &quot; entity.
  *
- * <example>
- * <title>A UI definition</title>
+ * ## A UI definition ##
+ *
  * |[
  * <ui>
  *   <menubar>
@@ -149,12 +149,12 @@
  *   </toolbar>
  * </ui>
  * ]|
- * </example>
  *
  * 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>
@@ -197,11 +197,9 @@
  * 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>
+ *
+ * # UI Merging # {#UI-Merging}
+ *
  * The most remarkable feature of #GtkUIManager is that it can overlay a set
  * of menuitems and toolitems over another one, and demerge them later.
  *
@@ -211,20 +209,16 @@
  * 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>
+ *
+ * # Accelerators #
+ *
  * 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>
+ *
+ * # Smart Separators # {#Smart-Separators}
+ *
  * 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
@@ -236,14 +230,13 @@
  * 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>
+ *
+ * # Empty Menus
+ *
  * 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>
@@ -252,13 +245,12 @@
  * <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>
+ *
+ * # GtkUIManager as GtkBuildable # {#GtkUIManager-BUILDER-UI}
+ *
  * The GtkUIManager implementation of the GtkBuildable interface accepts
  * GtkActionGroup objects as &lt;child&gt; elements in UI definitions.
  *
@@ -269,8 +261,8 @@
  * other parts of the constructed user interface with the help of the
  * "constructor" attribute. See the example below.
  *
- * <example>
- * <title>An embedded GtkUIManager UI definition</title>
+ * ## An embedded GtkUIManager UI definition
+ *
  * |[
  * <object class="GtkUIManager" id="uiman">
  *   <child>
@@ -295,9 +287,6 @@
  *   </child>
  * </object>
  * ]|
- * </example>
- * </para>
- * </refsect2>
  */