docs: replace all <examples> with markdown headings

32 files changed, 121 insertions, 165 deletions

diff --git a/gdk/gdkapplaunchcontext.c b/gdk/gdkapplaunchcontext.c
index 22e517790c..f84367da55 100644
--- a/gdk/gdkapplaunchcontext.c
+++ b/gdk/gdkapplaunchcontext.c
@@ -34,8 +34,9 @@
  * handles launching an application in a graphical context. It provides
  * startup notification and allows to launch applications on a specific
  * screen or workspace.
- * <example>
- * <title>Launching an application</title>
+ *
+ * ## Launching an application
+ *
  * |[<!-- language="C" -->
  * GdkAppLaunchContext *context;
  *
@@ -49,7 +50,6 @@
  *
  * g_object_unref (context);
  * ]|
- * </example>
  */
 
 
diff --git a/gdk/gdkdevicemanager.c b/gdk/gdkdevicemanager.c
index cb2f227d7e..ace175d0e5 100644
--- a/gdk/gdkdevicemanager.c
+++ b/gdk/gdkdevicemanager.c
@@ -77,7 +77,8 @@
  * be controlling each of these virtual devices. Physical devices may also
  * be "floating", which means they are not attached to any virtual device.
  *
- * <example><title>Master and slave devices</title>
+ * ## Master and slave devices
+ *
  * <screen>
  * carlos@sacarino:~$ xinput list
  * ⎡ Virtual core pointer                          id=2    [master pointer  (3)]
@@ -96,7 +97,6 @@
  *     ↳ AT Translated Set 2 keyboard              id=12   [slave  keyboard (3)]
  *     ↳ ThinkPad Extra Buttons                    id=15   [slave  keyboard (3)]
  * </screen>
- * </example>
  *
  * By default, GDK will automatically listen for events coming from all
  * master devices, setting the #GdkDevice for all events coming from input
diff --git a/gdk/gdkdisplay.c b/gdk/gdkdisplay.c
index 39f310e7c8..c7cfabdfb4 100644
--- a/gdk/gdkdisplay.c
+++ b/gdk/gdkdisplay.c
@@ -2107,8 +2107,8 @@ static GQueue gdk_error_traps = G_QUEUE_INIT;
  * You can use gdk_x11_display_error_trap_push() to ignore errors
  * on only a single display.
  *
-* <example>
- * <title>Trapping an X error</title>
+ * ## Trapping an X error
+ *
  * |[<!-- language="C" -->
  * gdk_error_trap_push (<!-- -->);
  *
@@ -2120,7 +2120,6 @@ static GQueue gdk_error_traps = G_QUEUE_INIT;
  *    // ... Handle the error here ...
  *  }
  * ]|
- * </example>
  */
 void
 gdk_error_trap_push (void)
diff --git a/gdk/gdkdisplaymanager.c b/gdk/gdkdisplaymanager.c
index 98700373d3..193164a68c 100644
--- a/gdk/gdkdisplaymanager.c
+++ b/gdk/gdkdisplaymanager.c
@@ -85,8 +85,8 @@
  * you are building your application against. At runtime, use type-check
  * macros like GDK_IS_X11_DISPLAY() to find out which backend is in use:
  *
- * <example id="backend-specific">
- * <title>Backend-specific code</title>
+ * ## Backend-specific code ## {#backend-specific}
+ *
  * |[<!-- language="C" -->
  * #ifdef GDK_WINDOWING_X11
  *   if (GDK_IS_X11_DISPLAY (display))
@@ -104,7 +104,6 @@
  * #endif
  *   g_error ("Unsupported GDK backend");
  * ]|
- * </example>
  */
 
 
diff --git a/gdk/gdkpango.c b/gdk/gdkpango.c
index 9b2b8542cd..b1d4eca2c7 100644
--- a/gdk/gdkpango.c
+++ b/gdk/gdkpango.c
@@ -49,8 +49,9 @@
  *
  * Rendering a Pango layout is done most simply with pango_cairo_show_layout();
  * you can also draw pieces of the layout with pango_cairo_show_layout_line().
- * <example id="rotated-example">
- * <title>Draw transformed text with Pango and cairo</title>
+ *
+ * ## Draw transformed text with Pango and cairo ## {#rotated-example}
+ *
  * <!-- Note that this example is basically the same as
  *      demos/gtk-demo/rotated_text.c -->
  * |[<!-- language="C" -->
@@ -117,7 +118,7 @@
  * g_object_unref (layout);
  * g_object_unref (context);
  * ]|
- * </example>
+ *
  * <figure>
  *   <title>Output of <xref linkend="rotated-example"/></title>
  *   <graphic fileref="rotated-text.png" format="PNG"/>
diff --git a/gtk/gtkaccellabel.c b/gtk/gtkaccellabel.c
index 5be7750a08..1b4cb77c87 100644
--- a/gtk/gtkaccellabel.c
+++ b/gtk/gtkaccellabel.c
@@ -65,8 +65,9 @@
  * set (see #GtkAccelFlags).
  * A #GtkAccelLabel can display multiple accelerators and even signal names,
  * though it is almost always used to display just one accelerator key.
- * <example>
- * <title>Creating a simple menu item with an accelerator key.</title>
+ *
+ * ## Creating a simple menu item with an accelerator key.
+ *
  * |[<!-- language="C" -->
  *   GtkWidget *save_item;
  *   GtkAccelGroup *accel_group;
@@ -87,7 +88,6 @@
  *   gtk_widget_add_accelerator (save_item, "activate", accel_group,
  *                               GDK_KEY_s, GDK_CONTROL_MASK, GTK_ACCEL_VISIBLE);
  * ]|
- * </example>
  */
 
 enum {
diff --git a/gtk/gtkapplication.c b/gtk/gtkapplication.c
index 87cbf5daab..e4cbea9c7c 100644
--- a/gtk/gtkapplication.c
+++ b/gtk/gtkapplication.c
@@ -93,13 +93,13 @@
  * <graphic fileref="bloatpad-xfce.png" format="PNG"/>
  * </figure>
  *
- * <example id="gtkapplication"><title>A simple application</title>
+ * ## A simple application ## {#gtkapplication}
+ *
  * |[<!-- language="C" -->
  * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../examples/bloatpad.c">
  *  <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
  * </xi:include>
  * ]|
- * </example>
  *
  * GtkApplication optionally registers with a session manager
  * of the users session (if you set the #GtkApplication:register-session
diff --git a/gtk/gtkapplicationwindow.c b/gtk/gtkapplicationwindow.c
index 9b795d12a2..7b4679082c 100644
--- a/gtk/gtkapplicationwindow.c
+++ b/gtk/gtkapplicationwindow.c
@@ -78,7 +78,8 @@
  * also be shown as part of client-side window decorations, e.g. by
  * using gtk_header_bar_set_show_close_button().
  *
- * <example><title>A GtkApplicationWindow with a menubar</title>
+ * ## A GtkApplicationWindow with a menubar
+ *
  * |[<!-- language="C" -->
  * app = gtk_application_new ();
  *
@@ -100,9 +101,9 @@
  *
  * window = gtk_application_window_new (app);
  * ]|
- * </example>
  *
- * <example><title>Handling fallback yourself</title>
+ * ## Handling fallback yourself
+ *
  * |[<!-- language="C" -->
  * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../examples/sunny.c">
  *  <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
diff --git a/gtk/gtkdrawingarea.c b/gtk/gtkdrawingarea.c
index 50ff45abe5..79d58928cd 100644
--- a/gtk/gtkdrawingarea.c
+++ b/gtk/gtkdrawingarea.c
@@ -60,8 +60,8 @@
  * background color before sending the expose event, and that
  * drawing is implicitly clipped to the exposed area.
  *
- * <example>
- * <title>Simple GtkDrawingArea usage</title>
+ * ## Simple GtkDrawingArea usage
+ *
  * |[<!-- language="C" -->
  * gboolean
  * draw_callback (GtkWidget *widget, cairo_t *cr, gpointer data)
@@ -91,7 +91,6 @@
  *   g_signal_connect (G_OBJECT (drawing_area), "draw",
  *                     G_CALLBACK (draw_callback), NULL);
  * ]|
- * </example>
  *
  * Draw signals are normally delivered when a drawing area first comes
  * onscreen, or when it's covered by another window and then uncovered.
diff --git a/gtk/gtkeditable.c b/gtk/gtkeditable.c
index e57efdd63e..a2bba6879e 100644
--- a/gtk/gtkeditable.c
+++ b/gtk/gtkeditable.c
@@ -37,8 +37,8 @@
  * the following handler to #GtkEditable::insert-text, an application
  * can convert all entry into a widget into uppercase.
  *
- * <example>
- * <title>Forcing entry to uppercase.</title>
+ * ## Forcing entry to uppercase.
+ *
  * |[<!-- language="C" -->
  * #include <ctype.h>;
  *
@@ -62,7 +62,6 @@
  *   g_free (result);
  * }
  * ]|
- * </example>
  */
 
 #include "config.h"
diff --git a/gtk/gtkfilechooser.c b/gtk/gtkfilechooser.c
index 00d0c0c569..9aa044ba88 100644
--- a/gtk/gtkfilechooser.c
+++ b/gtk/gtkfilechooser.c
@@ -321,8 +321,9 @@ gtk_file_chooser_default_init (GtkFileChooserInterface *iface)
    * dialog should be used, it should return
    * %GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM. The following example
    * illustrates this.
-   * <example id="gtkfilechooser-confirmation">
-   * <title>Custom confirmation</title>
+   *
+   * ## Custom confirmation ## {#gtkfilechooser-confirmation}
+   *
    * |[<!-- language="C" -->
    * static GtkFileChooserConfirmation
    * confirm_overwrite_callback (GtkFileChooser *chooser, gpointer data)
@@ -354,7 +355,6 @@ gtk_file_chooser_default_init (GtkFileChooserInterface *iface)
    *
    * gtk_widget_destroy (chooser);
    * ]|
-   * </example>
    *
    * Returns: a #GtkFileChooserConfirmation value that indicates which
    *  action to take after emitting the signal.
diff --git a/gtk/gtkfilechooserbutton.c b/gtk/gtkfilechooserbutton.c
index c639b71804..dc448968b7 100644
--- a/gtk/gtkfilechooserbutton.c
+++ b/gtk/gtkfilechooserbutton.c
@@ -70,8 +70,8 @@
  * that button.  This widget does not support setting the
  * #GtkFileChooser:select-multiple property to %TRUE.
  *
- * <example>
- * <title>Create a button to let the user select a file in /etc</title>
+ * ## Create a button to let the user select a file in /etc
+ *
  * |[<!-- language="C" -->
  * {
  *   GtkWidget *button;
@@ -82,7 +82,6 @@
  *                                        "/etc");
  * }
  * ]|
- * </example>
  *
  * The #GtkFileChooserButton supports the #GtkFileChooserAction<!-- -->s
  * %GTK_FILE_CHOOSER_ACTION_OPEN and %GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER.
diff --git a/gtk/gtkfilechooserdialog.c b/gtk/gtkfilechooserdialog.c
index c52bc96141..a3efe171c5 100644
--- a/gtk/gtkfilechooserdialog.c
+++ b/gtk/gtkfilechooserdialog.c
@@ -52,11 +52,11 @@
  * own.  Instead, you should use the functions that work on a
  * #GtkFileChooser.
  *
- * <example id="gtkfilechooser-typical-usage">
- * <title>Typical usage</title>
+ * ## Typical usage ## {#gtkfilechooser-typical-usage}
+ *
  * In the simplest of cases, you can the following code to use
  * #GtkFileChooserDialog to select a file for opening:
- * <para>
+ *
  * |[
  * GtkWidget *dialog;
  *
@@ -78,9 +78,9 @@
  *
  * gtk_widget_destroy (dialog);
  * ]|
- * </para>
+ *
  * To use a dialog for saving, you can use this:
- * <para>
+ *
  * |[
  * GtkWidget *dialog;
  *
@@ -108,14 +108,10 @@
  *
  * gtk_widget_destroy (dialog);
  * ]|
- * </para>
- * </example>
  *
- * ## Setting up a file chooser dialog
+ * ## Setting up a file chooser dialog ## {#gtkfilechooserdialog-setting-up}
  *
- * <para id="gtkfilechooserdialog-setting-up">
  * There are various cases in which you may need to use a #GtkFileChooserDialog:
- * </para>
  *
  * - To select a file for opening. Use #GTK_FILE_CHOOSER_ACTION_OPEN.
  *
@@ -138,13 +134,13 @@
  * i.e. when you are doing a Save As command and you already
  * have a file saved somewhere.
 
- * ## Response Codes
+ * ## Response Codes ## {#gtkfilechooserdialog-responses}
  *
- * <para id="gtkfilechooserdialog-response-codes">
  * #GtkFileChooserDialog inherits from #GtkDialog, so buttons that
  * go in its action area have response codes such as
  * #GTK_RESPONSE_ACCEPT and #GTK_RESPONSE_CANCEL.  For example, you
  * could call gtk_file_chooser_dialog_new() as follows:
+ *
  * |[
  * GtkWidget *dialog;
  *
@@ -155,16 +151,14 @@
  *                                       _("_Open"), GTK_RESPONSE_ACCEPT,
  *                                       NULL);
  * ]|
- * </para>
  *
- * <para id="gtkfilechooserdialog-responses">
  * This will create buttons for "Cancel" and "Open" that use stock
  * response identifiers from #GtkResponseType.  For most dialog
  * boxes you can use your own custom response codes rather than the
  * ones in #GtkResponseType, but #GtkFileChooserDialog assumes that
  * its "accept"-type action, e.g. an "Open" or "Save" button,
  * will have one of the following response codes:
- * </para>
+ *
  * - #GTK_RESPONSE_ACCEPT
  * - #GTK_RESPONSE_OK
  * - #GTK_RESPONSE_YES
diff --git a/gtk/gtkimage.c b/gtk/gtkimage.c
index d69d8608da..b430b625c6 100644
--- a/gtk/gtkimage.c
+++ b/gtk/gtkimage.c
@@ -74,8 +74,9 @@
  * so by default does not receive events. If you want to receive events
  * on the image, such as button clicks, place the image inside a
  * #GtkEventBox, then connect to the event signals on the event box.
- * <example>
- * <title>Handling button press events on a #GtkImage.</title>
+ *
+ * ## Handling button press events on a #GtkImage.
+ *
  * |[<!-- language="C" -->
  *   static gboolean
  *   button_press_callback (GtkWidget      *event_box,
@@ -113,7 +114,6 @@
  *     return image;
  *   }
  * ]|
- * </example>
  *
  * When handling events on the event box, keep in mind that coordinates
  * in the image may be different from event box coordinates due to
diff --git a/gtk/gtklevelbar.c b/gtk/gtklevelbar.c
index ef8599fbf1..d9e443f4d1 100644
--- a/gtk/gtklevelbar.c
+++ b/gtk/gtklevelbar.c
@@ -33,8 +33,8 @@
  * by default on the level bar: #GTK_LEVEL_BAR_OFFSET_LOW and
  * #GTK_LEVEL_BAR_OFFSET_HIGH, with values 0.25 and 0.75 respectively.
  *
- * <example>
- * <title>Adding a custom offset on the bar</title>
+ * ## Adding a custom offset on the bar
+ *
  * |[<!-- language="C" -->
  *
  * static GtkWidget *
@@ -66,7 +66,6 @@
  *   return level_bar;
  * }
  * ]|
- * </example>
  *
  * The default interval of values is between zero and one, but it's possible to
  * modify the interval using gtk_level_bar_set_min_value() and
diff --git a/gtk/gtkmain.c b/gtk/gtkmain.c
index a2d019efec..fe19e42655 100644
--- a/gtk/gtkmain.c
+++ b/gtk/gtkmain.c
@@ -53,8 +53,8 @@
  * #GtkFileChooserDialog. After a callback finishes, GTK+ will return to the
  * main loop and await more user input.
  *
- * <example>
- * <title>Typical main() function for a GTK+ application</title>
+ * ## Typical main() function for a GTK+ application
+ *
  * |[<!-- language="C" -->
  * int
  * main (int argc, char **argv)
@@ -81,7 +81,6 @@
  *   return 0;
  * }
  * ]|
- * </example>
  *
  * It's OK to use the GLib main loop directly instead of gtk_main(), though it
  * involves slightly more typing. See #GMainLoop in the GLib documentation.
@@ -1247,8 +1246,8 @@ gtk_main_quit (void)
  * This can be used to update the UI and invoke timeouts etc.
  * while doing some time intensive computation.
  *
- * <example>
- * <title>Updating the UI during a long computation</title>
+ * ## Updating the UI during a long computation
+ *
  * |[<!-- language="C" -->
  *  /&ast; computation going on... &ast;/
  *
@@ -1257,7 +1256,6 @@ gtk_main_quit (void)
  *
  *  /&ast; ...computation continued &ast;/
  * ]|
- * </example>
  *
  * Returns: %TRUE if any events are pending, %FALSE otherwise
  */
@@ -1804,8 +1802,8 @@ gtk_main_do_event (GdkEvent *event)
  * of a window. Of course you should not do this as the user expects
  * a reaction from clicking the close icon of the window...
  *
- * <example>
- * <title>A persistent window</title>
+ * ## A persistent window
+ *
  * |[<!-- language="C" -->
  * #include <gtk/gtk.h>
  *
@@ -1834,7 +1832,6 @@ gtk_main_do_event (GdkEvent *event)
  *   return 0;
  * }
  * ]|
- * </example>
  *
  * Returns: %TRUE
  */
diff --git a/gtk/gtkmenu.c b/gtk/gtkmenu.c
index 909e27d3ed..978b9dd729 100644
--- a/gtk/gtkmenu.c
+++ b/gtk/gtkmenu.c
@@ -43,17 +43,16 @@
  * gtk_menu_popup() function.  The example below shows how an application
  * can pop up a menu when the 3rd mouse button is pressed.  
  *
- * <example>
- * <title>Connecting the popup signal handler.</title>
+ * ## Connecting the popup signal handler.
+ *
  * |[<!-- language="C" -->
  *   /<!---->* connect our handler which will popup the menu *<!---->/
  *   g_signal_connect_swapped (window, "button_press_event",
  *	G_CALLBACK (my_popup_handler), menu);
  * ]|
- * </example>
  *
- * <example>
- * <title>Signal handler which displays a popup menu.</title>
+ * ## Signal handler which displays a popup menu.
+ *
  * |[<!-- language="C" -->
  * static gint
  * my_popup_handler (GtkWidget *widget, GdkEvent *event)
@@ -80,11 +79,10 @@
  *           return TRUE;
  *         }
  *     }
- * 
+ *
  *   return FALSE;
  * }
  * ]|
- * </example>
  */
 
 #include "config.h"
diff --git a/gtk/gtkpagesetup.c b/gtk/gtkpagesetup.c
index 63fef1f8fc..fd003b282d 100644
--- a/gtk/gtkpagesetup.c
+++ b/gtk/gtkpagesetup.c
@@ -48,8 +48,8 @@
  * or use gtk_print_run_page_setup_dialog() to show the page setup dialog
  * and receive the resulting page setup.
  *
- * <example>
- * <title>A page setup dialog</title>
+ * ## A page setup dialog
+ *
  * |[<!-- language="C" -->
  * static GtkPrintSettings *settings = NULL;
  * static GtkPageSetup *page_setup = NULL;
@@ -71,7 +71,6 @@
  *   page_setup = new_page_setup;
  * }
  * ]|
- * </example>
  *
  * Printing support was added in GTK+ 2.10.
  */
diff --git a/gtk/gtkpaned.c b/gtk/gtkpaned.c
index 67931ac496..856a5ba115 100644
--- a/gtk/gtkpaned.c
+++ b/gtk/gtkpaned.c
@@ -73,8 +73,8 @@
  * The application can set the position of the slider as if it were set
  * by the user, by calling gtk_paned_set_position().
  *
- * <example>
- * <title>Creating a paned widget with minimum sizes.</title>
+ * ## Creating a paned widget with minimum sizes.
+ *
  * |[<!-- language="C" -->
  * GtkWidget *hpaned = gtk_paned_new (GTK_ORIENTATION_HORIZONTAL);
  * GtkWidget *frame1 = gtk_frame_new (NULL);
@@ -90,7 +90,6 @@
  * gtk_paned_pack2 (GTK_PANED (hpaned), frame2, FALSE, FALSE);
  * gtk_widget_set_size_request (frame2, 50, -1);
  * ]|
- * </example>
  */
 
 enum {
diff --git a/gtk/gtkprintcontext.c b/gtk/gtkprintcontext.c
index 97d56e50c8..fe3d4234d8 100644
--- a/gtk/gtkprintcontext.c
+++ b/gtk/gtkprintcontext.c
@@ -35,8 +35,8 @@
  * #GtkPrintOperation::end-print, #GtkPrintOperation::request-page-setup and
  * #GtkPrintOperation::draw-page signals on the #GtkPrintOperation.
  *
- * <example>
- * <title>Using GtkPrintContext in a #GtkPrintOperation::draw-page callback</title>
+ * ## Using GtkPrintContext in a #GtkPrintOperation::draw-page callback
+ *
  * |[<!-- language="C" -->
  * static void
  * draw_page (GtkPrintOperation *operation,
@@ -90,7 +90,6 @@
  *   g_object_unref (layout);
  * }
  * ]|
- * </example>
  *
  * Printing support was added in GTK+ 2.10.
  */
diff --git a/gtk/gtkprintoperation.c b/gtk/gtkprintoperation.c
index daf0d37c50..30195a9a4e 100644
--- a/gtk/gtkprintoperation.c
+++ b/gtk/gtkprintoperation.c
@@ -59,8 +59,8 @@
  * #GtkPrintOperation::draw-page, which you are supposed to catch
  * and render the page on the provided #GtkPrintContext using Cairo.
  *
- * <example>
- * <title>The high-level printing API</title>
+ * ## The high-level printing API
+ *
  * |[<!-- language="C" -->
  * static GtkPrintSettings *settings = NULL;
  *
@@ -91,7 +91,6 @@
  *   g_object_unref (print);
  * }
  * ]|
- * </example>
  *
  * By default GtkPrintOperation uses an external application to do
  * print preview. To implement a custom print preview, an application
diff --git a/gtk/gtkradiobutton.c b/gtk/gtkradiobutton.c
index 8d62e01886..fc7744403c 100644
--- a/gtk/gtkradiobutton.c
+++ b/gtk/gtkradiobutton.c
@@ -68,8 +68,8 @@
  * The group list does not need to be freed, as each #GtkRadioButton will remove
  * itself and its list item when it is destroyed.
  *
- * <example>
- * <title>How to create a group of two radio buttons.</title>
+ * ## How to create a group of two radio buttons.
+ *
  * |[<!-- language="C" -->
  * void create_radio_buttons (void) {
  *
@@ -96,7 +96,6 @@
  *    return;
  * }
  * ]|
- * </example>
  *
  * When an unselected button in the group is clicked the clicked button
  * receives the #GtkToggleButton::toggled signal, as does the previously
diff --git a/gtk/gtkradiomenuitem.c b/gtk/gtkradiomenuitem.c
index 8d1fc0e98e..04c192aa84 100644
--- a/gtk/gtkradiomenuitem.c
+++ b/gtk/gtkradiomenuitem.c
@@ -46,8 +46,8 @@
  * The correct way to create a group of radio menu items is approximatively
  * this:
  *
- * <example>
- * <title>How to create a group of radio menu items.</title>
+ * ## How to create a group of radio menu items.
+ *
  * |[<!-- language="C" -->
  * GSList *group = NULL;
  * GtkWidget *item;
@@ -61,10 +61,8 @@
  *     gtk_check_menu_item_set_active (GTK_CHECK_MENU_ITEM (item), TRUE);
  * }
  * ]|
- * </example>
  */
 
-
 struct _GtkRadioMenuItemPrivate
 {
   GSList *group;
diff --git a/gtk/gtkrecentchooserdialog.c b/gtk/gtkrecentchooserdialog.c
index cb0c2e1be4..8a5b98f61e 100644
--- a/gtk/gtkrecentchooserdialog.c
+++ b/gtk/gtkrecentchooserdialog.c
@@ -44,10 +44,11 @@
  * Note that #GtkRecentChooserDialog does not have any methods of its own.
  * Instead, you should use the functions that work on a #GtkRecentChooser.
  *
- * <example id="gtkrecentchooser-typical-usage">
- * <title>Typical usage</title>
+ * ## Typical usage ## {#gtkrecentchooser-typical-usage}
+ *
  * In the simplest of cases, you can use the following code to use
  * a #GtkRecentChooserDialog to select a recently used file:
+ *
  * |[<!-- language="C" -->
  * GtkWidget *dialog;
  *
@@ -68,7 +69,6 @@
  *
  * gtk_widget_destroy (dialog);
  * ]|
- * </example>
  *
  * Recently used files are supported since GTK+ 2.10.
  */
diff --git a/gtk/gtksearchbar.c b/gtk/gtksearchbar.c
index 969d34b935..dfde6887e2 100644
--- a/gtk/gtksearchbar.c
+++ b/gtk/gtksearchbar.c
@@ -54,14 +54,13 @@
  * The following example shows you how to create a more complex search
  * entry.
  *
- * <example>
- * <title>Creating a search bar</title>
+ * ## Creating a search bar
+ *
  * |[<!-- language="C" -->
  * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../examples/search-bar.c">
  *  <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
  * </xi:include>
  * ]|
- * </example>
  *
  * Since: 3.10
  */
@@ -166,8 +165,8 @@ preedit_changed_cb (GtkEntry  *entry,
  * gtk_search_bar_connect_entry(), this function will return
  * immediately with a warning.
  *
- * <example>
- * <title>Showing the search bar on key presses</title>
+ * ## Showing the search bar on key presses
+ *
  * |[<!-- language="C" -->
  * static gboolean
  * window_key_press_event_cb (GtkWidget *widget,
@@ -180,7 +179,6 @@ preedit_changed_cb (GtkEntry  *entry,
  * g_signal_connect (window, "key-press-event",
  *                   G_CALLBACK (window_key_press_event_cb), search_bar);
  * ]|
- * </example>
  *
  * Return value: %GDK_EVENT_STOP if the key press event resulted
  *     in text being entered in the search entry (and revealing
diff --git a/gtk/gtksocket.c b/gtk/gtksocket.c
index ffd50c46d4..aab1a94de4 100644
--- a/gtk/gtksocket.c
+++ b/gtk/gtksocket.c
@@ -68,8 +68,8 @@
  * Before using this function, the socket must have been realized,
  * and for hence, have been added to its parent.
  *
- * <example>
- * <title>Obtaining the window ID of a socket.</title>
+ * ## Obtaining the window ID of a socket.
+ *
  * |[<!-- language="C" -->
  * GtkWidget *socket = gtk_socket_new (<!-- -->);
  * gtk_widget_show (socket);
@@ -82,7 +82,6 @@
  * g_print ("The ID of the sockets window is %#x\n",
  *          gtk_socket_get_id (socket));
  * ]|
- * </example>
  *
  * Note that if you pass the window ID of the socket to another
  * process that will create a plug in the socket, you must make
diff --git a/gtk/gtkspinbutton.c b/gtk/gtkspinbutton.c
index 5734d2cbe2..0a2c2b1c68 100644
--- a/gtk/gtkspinbutton.c
+++ b/gtk/gtkspinbutton.c
@@ -78,8 +78,8 @@
  * See the #GtkAdjustment section for more details about an adjustment's
  * properties.
  *
- * <example>
- * <title>Using a GtkSpinButton to get an integer</title>
+ * ## Using a GtkSpinButton to get an integer
+ *
  * |[<!-- language="C" -->
  * /&ast; Provides a function to retrieve an integer value from a
  *  &ast; GtkSpinButton and creates a spin button to model percentage
@@ -112,10 +112,9 @@
  *   gtk_widget_show_all (window);
  * }
  * ]|
- * </example>
  *
- * <example>
- * <title>Using a GtkSpinButton to get a floating point value</title>
+ * ## Using a GtkSpinButton to get a floating point value
+ *
  * |[<!-- language="C" -->
  * /&ast; Provides a function to retrieve a floating point value from a
  *  &ast; GtkSpinButton, and creates a high precision spin button.
@@ -146,7 +145,6 @@
  *   gtk_widget_show_all (window);
  * }
  * ]|
- * </example>
  */
 
 struct _GtkSpinButtonPrivate
diff --git a/gtk/gtkstylecontext.c b/gtk/gtkstylecontext.c
index 0117b441e3..247d1ca1c9 100644
--- a/gtk/gtkstylecontext.c
+++ b/gtk/gtkstylecontext.c
@@ -3706,10 +3706,9 @@ _gtk_style_context_get_cursor_color (GtkStyleContext *context,
  * on or off, and %GTK_STATE_FLAG_INCONSISTENT determines whether it
  * should be marked as undefined.
  *
- * <example>
- * <title>Typical checkmark rendering</title>
+ * Typical checkmark rendering:
+ *
  * ![](checks.png)
- * </example>
  *
  * Since: 3.0
  **/
@@ -3757,10 +3756,9 @@ gtk_render_check (GtkStyleContext *context,
  * state will determine whether the option is on or off, and
  * %GTK_STATE_FLAG_INCONSISTENT whether it should be marked as undefined.
  *
- * <example>
- * <title>Typical option mark rendering</title>
+ * Typical option mark rendering:
+ *
  * ![](options.png)
- * </example>
  *
  * Since: 3.0
  **/
@@ -3805,10 +3803,9 @@ gtk_render_option (GtkStyleContext *context,
  *
  * Renders an arrow pointing to @angle.
  *
- * <example>
- * <title>Typical arrow rendering at 0, 1&solidus;2 &pi;, &pi; and 3&solidus;2 &pi;</title>
+ * Typical arrow rendering at 0, 1&solidus;2 &pi;, &pi; and 3&solidus;2 &pi;:
+ *
  * ![](arrows.png)
- * </example>
  *
  * Since: 3.0
  **/
@@ -3857,13 +3854,12 @@ gtk_render_arrow (GtkStyleContext *context,
  *
  * Renders the background of an element.
  *
- * <example>
- * <title>Typical background rendering, showing the effect of
+ * Typical background rendering, showing the effect of
  * <parameter>background-image</parameter>,
  * <parameter>border-width</parameter> and
- * <parameter>border-radius</parameter></title>
+ * <parameter>border-radius</parameter>:
+ *
  * ![](background.png)
- * </example>
  *
  * Since: 3.0.
  **/
@@ -3907,15 +3903,13 @@ gtk_render_background (GtkStyleContext *context,
  *
  * Renders a frame around the rectangle defined by @x, @y, @width, @height.
  *
- * <example>
- * <title>Examples of frame rendering, showing the effect of
+ * Examples of frame rendering, showing the effect of
  * <parameter>border-image</parameter>,
  * <parameter>border-color</parameter>,
  * <parameter>border-width</parameter>,
- * <parameter>border-radius</parameter> and
- * junctions</title>
+ * <parameter>border-radius</parameter> and junctions:
+ *
  * ![](frames.png)
- * </example>
  *
  * Since: 3.0
  **/
@@ -3961,10 +3955,9 @@ gtk_render_frame (GtkStyleContext *context,
  * defined by @x, @y, @width, @height. The state %GTK_STATE_FLAG_ACTIVE
  * determines whether the expander is collapsed or expanded.
  *
- * <example>
- * <title>Typical expander rendering</title>
+ * Typical expander rendering:
+ *
  * ![](expanders.png)
- * </example>
  *
  * Since: 3.0
  **/
@@ -4007,10 +4000,10 @@ gtk_render_expander (GtkStyleContext *context,
  * @height: rectangle height
  *
  * Renders a focus indicator on the rectangle determined by @x, @y, @width, @height.
- * <example>
- * <title>Typical focus rendering</title>
+ *
+ * Typical focus rendering:
+ *
  * ![](focus.png)
- * </example>
  *
  * Since: 3.0
  **/
@@ -4134,10 +4127,9 @@ gtk_render_line (GtkStyleContext *context,
  * @width, @height. @orientation defines whether the slider is vertical
  * or horizontal.
  *
- * <example>
- * <title>Typical slider rendering</title>
+ * Typical slider rendering:
+ *
  * ![](sliders.png)
- * </example>
  *
  * Since: 3.0
  **/
@@ -4188,10 +4180,9 @@ gtk_render_slider (GtkStyleContext *context,
  * for %GTK_POS_TOP and %GTK_POS_BOTTOM gap sides, and Y coordinates for
  * %GTK_POS_LEFT and %GTK_POS_RIGHT.
  *
- * <example>
- * <title>Typical rendering of a frame with a gap</title>
+ * Typical rendering of a frame with a gap:
+ *
  * ![](frame-gap.png)
- * </example>
  *
  * Since: 3.0
  **/
@@ -4251,10 +4242,9 @@ gtk_render_frame_gap (GtkStyleContext *context,
  * defined by @x, @y, @width, @height. The side where the extension
  * connects to is defined by @gap_side.
  *
- * <example>
- * <title>Typical extension rendering</title>
+ * Typical extension rendering:
+ *
  * ![](extensions.png)
- * </example>
  *
  * Since: 3.0
  **/
@@ -4301,10 +4291,9 @@ gtk_render_extension (GtkStyleContext *context,
  * #GtkWindow<!-- -->'s resize grip), in the rectangle
  * determined by @x, @y, @width, @height.
  *
- * <example>
- * <title>Handles rendered for the paned and grip classes</title>
+ * Handles rendered for the paned and grip classes:
+ *
  * ![](handles.png)
- * </example>
  *
  * Since: 3.0
  **/
diff --git a/gtk/gtktogglebutton.c b/gtk/gtktogglebutton.c
index b43350b484..11dc951712 100644
--- a/gtk/gtktogglebutton.c
+++ b/gtk/gtktogglebutton.c
@@ -58,8 +58,8 @@
  *
  * To simply switch the state of a toggle button, use gtk_toggle_button_toggled().
  *
- * <example>
- * <title>Creating two #GtkToggleButton widgets.</title>
+ * ## Creating two #GtkToggleButton widgets.
+ *
  * |[<!-- language="C" -->
  * void make_toggles (void) {
  *    GtkWidget *dialog, *toggle1, *toggle2;
@@ -85,7 +85,6 @@
  *    gtk_widget_show_all (dialog);
  * }
  * ]|
- * </example>
  */
 
 
diff --git a/gtk/gtktreemodel.c b/gtk/gtktreemodel.c
index 931d9ff766..f12309bf76 100644
--- a/gtk/gtktreemodel.c
+++ b/gtk/gtktreemodel.c
@@ -114,8 +114,8 @@
  * easier, the second is much more common, as you often get paths from
  * callbacks.
  *
- * <example>
- * <title>Acquiring a #GtkTreeIter-struct</title>
+ * ## Acquiring a #GtkTreeIter-struct
+ *
  * |[<!-- language="C" -->
  *  /&ast; Three ways of getting the iter pointing to the location &ast;/
  * GtkTreePath *path;
@@ -137,7 +137,6 @@
  * parent_iter = iter;
  * gtk_tree_model_iter_nth_child (model, &iter, &parent_iter, 5);
  * ]|
- * </example>
  *
  * This second example shows a quick way of iterating through a list
  * and getting a string and an integer from each row. The
@@ -145,8 +144,8 @@
  * shown, as it is specific to the #GtkListStore. For information on
  * how to write such a function, see the #GtkListStore documentation.
  *
- * <example>
- * <title>Reading data from a #GtkTreeModel</title>
+ * ## Reading data from a #GtkTreeModel
+ *
  * |[<!-- language="C" -->
  * enum
  * {
@@ -192,7 +191,6 @@
  *    row_count++;
  *  }
  * ]|
- * </example>
  *
  * The #GtkTreeModel interface contains two methods for reference
  * counting: gtk_tree_model_ref_node() and gtk_tree_model_unref_node().
diff --git a/gtk/gtktreemodelsort.c b/gtk/gtktreemodelsort.c
index f545ae7eb3..9d294e82b6 100644
--- a/gtk/gtktreemodelsort.c
+++ b/gtk/gtktreemodelsort.c
@@ -50,8 +50,8 @@
  * simply put the same model in each widget, then sorting the first would
  * sort the second.
  *
- * <example>
- * <title>Using a #GtkTreeModelSort</title>
+ * ## Using a #GtkTreeModelSort
+ *
  * |[<!-- language="C" -->
  * {
  *   GtkTreeView *tree_view1;
@@ -78,7 +78,6 @@
  *                                         COLUMN_1, GTK_SORT_DESCENDING);
  * }
  * ]|
- * </example>
  *
  * To demonstrate how to access the underlying child model from the sort
  * model, the next example will be a callback for the #GtkTreeSelection
@@ -86,8 +85,8 @@
  * from COLUMN_1 of the model.  We then modify the string, find the same
  * selected row on the child model, and change the row there.
  *
- * <example>
- * <title>Accessing the child model of in a selection changed callback</title>
+ * ## Accessing the child model of in a selection changed callback
+ *
  * |[<!-- language="C" -->
  * void
  * selection_changed (GtkTreeSelection *selection, gpointer data)
@@ -131,7 +130,6 @@
  *   g_free (modified_data);
  * }
  * ]|
- * </example>
  */
 
 
diff --git a/gtk/gtkwidgetpath.c b/gtk/gtkwidgetpath.c
index 9bfa58e6e6..fa431da197 100644
--- a/gtk/gtkwidgetpath.c
+++ b/gtk/gtkwidgetpath.c
@@ -40,8 +40,9 @@
  * updated on widget hierarchy changes.
  *
  * The widget path generation is generally simple:
- * <example>
- * <title>Defining a button within a window</title>
+ *
+ * ## Defining a button within a window
+ *
  * |[<!-- language="C" -->
  * {
  *   GtkWidgetPath *path;
@@ -51,14 +52,13 @@
  *   gtk_widget_path_append_type (path, GTK_TYPE_BUTTON);
  * }
  * ]|
- * </example>
  *
  * Although more complex information, such as widget names, or
  * different classes (property that may be used by other widget
  * types) and intermediate regions may be included:
  *
- * <example>
- * <title>Defining the first tab widget in a notebook</title>
+ * ## Defining the first tab widget in a notebook
+ *
  * |[<!-- language="C" -->
  * {
  *   GtkWidgetPath *path;
@@ -73,7 +73,6 @@
  *   gtk_widget_path_iter_set_name (path, pos, "first tab label");
  * }
  * ]|
- * </example>
  *
  * All this information will be used to match the style information
  * that applies to the described widget.