docs: use markdown instead of <note>

gdk/gdkevents.h

@@ -45,12 +45,8 @@ G_BEGIN_DECLS
  *
  * The event structures contain data specific to each type of event in GDK.
  *
- * <note>
+ * > A common mistake is to forget to set the event mask of a widget so that
- * <para>
+ * > the required events are received. See gtk_widget_set_events().
- * A common mistake is to forget to set the event mask of a widget so that
- * the required events are received. See gtk_widget_set_events().
- * </para>
- * </note>
  */
 
 

gdk/x11/gdkdevicemanager-x11.c

@@ -124,13 +124,11 @@ gdk_x11_device_manager_lookup (GdkDeviceManager *device_manager,
  *
  * Returns the device ID as seen by XInput2.
  *
- * <note>
+ * > If gdk_disable_multidevice() has been called, this function
- *   If gdk_disable_multidevice() has been called, this function
+ * > will respectively return 2/3 for the core pointer and keyboard,
- *   will respectively return 2/3 for the core pointer and keyboard,
+ * > (matching the IDs for the Virtual Core Pointer and Keyboard in
- *   (matching the IDs for the Virtual Core Pointer and Keyboard in
+ * > XInput 2), but calling this function on any slave devices (i.e.
- *   XInput 2), but calling this function on any slave devices (i.e.
+ * > those managed via XInput 1.x), will return 0.
- *   those managed via XInput 1.x), will return 0.
- * </note>
  *
  * Returns: the XInput2 device ID.
  *

gtk/deprecated/gtkactivatable.c

@@ -274,12 +274,12 @@ gtk_activatable_default_init (GtkActivatableInterface *iface)
 {
   /**
    * GtkActivatable:related-action:
-   * 
+   *
    * The action that this activatable will activate and receive
    * updates from for various states and possibly appearance.
    *
-   * <note><para>#GtkActivatable implementors need to handle the this property and 
+   * > #GtkActivatable implementors need to handle the this property and
-   * call gtk_activatable_do_set_related_action() when it changes.</para></note>
+   * > call gtk_activatable_do_set_related_action() when it changes.
    *
    * Since: 2.16
    *
@@ -294,7 +294,7 @@ gtk_activatable_default_init (GtkActivatableInterface *iface)
 
   /**
    * GtkActivatable:use-action-appearance:
-   * 
+   *
    * Whether this activatable should reset its layout
    * and appearance when setting the related action or when
    * the action changes appearance.
@@ -302,9 +302,9 @@ gtk_activatable_default_init (GtkActivatableInterface *iface)
    * See the #GtkAction documentation directly to find which properties
    * should be ignored by the #GtkActivatable when this property is %FALSE.
    *
-   * <note><para>#GtkActivatable implementors need to handle this property
+   * > #GtkActivatable implementors need to handle this property
-   * and call gtk_activatable_sync_action_properties() on the activatable
+   * > and call gtk_activatable_sync_action_properties() on the activatable
-   * widget when it changes.</para></note>
+   * > widget when it changes.
    *
    * Since: 2.16
    *
@@ -375,8 +375,8 @@ gtk_activatable_sync_action_properties (GtkActivatable *activatable,
  *
  * Sets the related action on the @activatable object.
  *
- * <note><para>#GtkActivatable implementors need to handle the #GtkActivatable:related-action
+ * > #GtkActivatable implementors need to handle the #GtkActivatable:related-action
- * property and call gtk_activatable_do_set_related_action() when it changes.</para></note>
+ * > property and call gtk_activatable_do_set_related_action() when it changes.
  *
  * Since: 2.16
  *
@@ -416,10 +416,10 @@ gtk_activatable_action_notify (GtkAction      *action,
  * method is called when the related #GtkAction properties change
  * and registers to the action's proxy list.
  *
- * <note><para>Be careful to call this before setting the local
+ * > Be careful to call this before setting the local
- * copy of the #GtkAction property, since this function uses 
+ * > copy of the #GtkAction property, since this function uses 
- * gtk_activatable_get_related_action() to retrieve the
+ * > gtk_activatable_get_related_action() to retrieve the
- * previous action</para></note>
+ * > previous action.
  *
  * Since: 2.16
  *
@@ -517,10 +517,10 @@ gtk_activatable_get_related_action (GtkActivatable *activatable)
  * Sets whether this activatable should reset its layout and appearance
  * when setting the related action or when the action changes appearance
  *
- * <note><para>#GtkActivatable implementors need to handle the
+ * > #GtkActivatable implementors need to handle the
- * #GtkActivatable:use-action-appearance property and call
+ * > #GtkActivatable:use-action-appearance property and call
- * gtk_activatable_sync_action_properties() to update @activatable
+ * > gtk_activatable_sync_action_properties() to update @activatable
- * if needed.</para></note>
+ * > if needed.
  *
  * Since: 2.16
   *

gtk/deprecated/gtkactivatable.h

@@ -44,8 +44,9 @@ typedef struct _GtkActivatableIface GtkActivatableIface;
  * properties that are meant to effect the appearance accordingly.
  * @sync_action_properties: Called to update the activatable completely, this is called internally when
  * #GtkActivatable:related-action property is set or unset and by the implementor when
- * #GtkActivatable:use-action-appearance changes.<note><para>This method can be called
+ * #GtkActivatable:use-action-appearance changes.
- * with a %NULL action at times</para></note>
+ *
+ * > This method can be called with a %NULL action at times.
  *
  * Since: 2.16
  *

gtk/deprecated/gtkhandlebox.c

@@ -66,11 +66,9 @@
  * allocation will remain fixed as the height of the handlebox shrinks,
  * so the snap edge should be set to %GTK_POS_BOTTOM.
  *
- * <note>
+ * > #GtkHandleBox has been deprecated. It is very specialized, lacks features
- * #GtkHandleBox has been deprecated. It is very specialized, lacks features
+ * > to make it useful and most importantly does not fit well into modern
- * to make it useful and most importantly does not fit well into modern
+ * > application design. Do not use it. There is no replacement.
- * application design. Do not use it. There is no replacement.
- * </note>
  */
 
 

gtk/deprecated/gtkhseparator.c

@@ -39,12 +39,10 @@ G_GNUC_BEGIN_IGNORE_DEPRECATIONS
  * widgets within a window. It displays a horizontal line with a shadow to
  * make it appear sunken into the interface.
  *
- * <note>
+ * > The #GtkHSeparator widget is not used as a separator within menus.
- * The #GtkHSeparator widget is not used as a separator within menus.
+ * > To create a separator in a menu create an empty #GtkSeparatorMenuItem
- * To create a separator in a menu create an empty #GtkSeparatorMenuItem
+ * > widget using gtk_separator_menu_item_new() and add it to the menu with
- * widget using gtk_separator_menu_item_new() and add it to the menu with
+ * > gtk_menu_shell_append().
- * gtk_menu_shell_append().
- * </note>
  *
  * GtkHSeparator has been deprecated, use #GtkSeparator instead.
  */

gtk/deprecated/gtkstyle.c

@@ -4375,17 +4375,15 @@ gtk_widget_modify_fg (GtkWidget      *widget,
  * All other style values are left untouched.
  * See also gtk_widget_modify_style().
  *
- * <note><para>
+ * > Note that “no window” widgets (which have the %GTK_NO_WINDOW
- * Note that “no window” widgets (which have the %GTK_NO_WINDOW
+ * > flag set) draw on their parent container's window and thus may
- * flag set) draw on their parent container's window and thus may
+ * > not draw any background themselves. This is the case for e.g.
- * not draw any background themselves. This is the case for e.g.
+ * > #GtkLabel.
- * #GtkLabel.
+ * >
- * </para><para>
+ * > To modify the background of such widgets, you have to set the
- * To modify the background of such widgets, you have to set the
+ * > background color on their parent; if you want to set the background
- * background color on their parent; if you want to set the background
+ * > of a rectangular area around a label, try placing the label in
- * of a rectangular area around a label, try placing the label in
+ * > a #GtkEventBox widget and setting the background color on that.
- * a #GtkEventBox widget and setting the background color on that.
- * </para></note>
  *
  * Deprecated:3.0: Use gtk_widget_override_background_color() instead
  */
@@ -4475,17 +4473,15 @@ gtk_widget_modify_text (GtkWidget      *widget,
  * (see gtk_widget_modify_text()) for widgets such as #GtkEntry
  * and #GtkTextView. See also gtk_widget_modify_style().
  *
- * <note><para>
+ * > Note that “no window” widgets (which have the %GTK_NO_WINDOW
- * Note that “no window” widgets (which have the %GTK_NO_WINDOW
+ * > flag set) draw on their parent container's window and thus may
- * flag set) draw on their parent container's window and thus may
+ * > not draw any background themselves. This is the case for e.g.
- * not draw any background themselves. This is the case for e.g.
+ * > #GtkLabel.
- * #GtkLabel.
+ * >
- * </para><para>
+ * > To modify the background of such widgets, you have to set the
- * To modify the background of such widgets, you have to set the
+ * > base color on their parent; if you want to set the background
- * base color on their parent; if you want to set the background
+ * > of a rectangular area around a label, try placing the label in
- * of a rectangular area around a label, try placing the label in
+ * > a #GtkEventBox widget and setting the base color on that.
- * a #GtkEventBox widget and setting the base color on that.
- * </para></note>
  *
  * Deprecated:3.0: Use gtk_widget_override_background_color() instead
  */

gtk/deprecated/gtktable.c

@@ -60,11 +60,9 @@
  * gtk_table_set_homogeneous(), can be used to set whether all cells in the
  * table will resize themselves to the size of the largest widget in the table.
  *
- * <note>
+ * > #GtkTable has been deprecated. Use #GtkGrid instead. It provides the same
- * #GtkTable has been deprecated. Use #GtkGrid instead. It provides the same
+ * > capabilities as GtkTable for arranging widgets in a rectangular grid, but
- * capabilities as GtkTable for arranging widgets in a rectangular grid, but
+ * > does support height-for-width geometry management.
- * does support height-for-width geometry management.
- * </note>
  */
 
 

gtk/deprecated/gtktearoffmenuitem.c

@@ -51,8 +51,8 @@ G_GNUC_BEGIN_IGNORE_DEPRECATIONS
  * the tearoff menu can be reattached.  Activating it will erase the tearoff
  * menu window.
  *
- * <note>#GtkTearoffMenuItem is deprecated and should not be used in newly
+ * > #GtkTearoffMenuItem is deprecated and should not be used in newly
- * written code. Menus are not meant to be torn around.</note>
+ * > written code. Menus are not meant to be torn around.
  */
 
 

gtk/deprecated/gtkuimanager.c

@@ -65,11 +65,9 @@
  * The UI definitions are specified in an XML format which can be
  * roughly described by the following DTD.
  *
- * <note><para>
+ * > Do not confuse the GtkUIManager UI Definitions described here with
- * Do not confuse the GtkUIManager UI Definitions described here with
+ * > the similarly named <link linkend="BUILDER-UI">GtkBuilder UI
- * the similarly named <link linkend="BUILDER-UI">GtkBuilder UI
+ * > Definitions</link>.
- * Definitions</link>.
- * </para></note>
  *
  * |[
  * <!ELEMENT ui          (menubar|toolbar|popup|accelerator)* >

gtk/gtkmessagedialog.h

@@ -77,11 +77,10 @@ struct _GtkMessageDialogClass
  * Prebuilt sets of buttons for the dialog. If
  * none of these choices are appropriate, simply use %GTK_BUTTONS_NONE
  * then call gtk_dialog_add_buttons().
- * <note>
+ *
- *  Please note that %GTK_BUTTONS_OK, %GTK_BUTTONS_YES_NO
+ * > Please note that %GTK_BUTTONS_OK, %GTK_BUTTONS_YES_NO
- *  and %GTK_BUTTONS_OK_CANCEL are discouraged by the
+ * > and %GTK_BUTTONS_OK_CANCEL are discouraged by the
- *  [GNOME Human Interface Guidelines](http://library.gnome.org/devel/hig-book/stable/).
+ * > [GNOME Human Interface Guidelines](http://library.gnome.org/devel/hig-book/stable/).
- * </note>
  */
 typedef enum
 {