docs: use links instead of <xref>

gdk/gdkkeys.c

@@ -488,7 +488,7 @@ gdk_keymap_lookup_key (GdkKeymap          *keymap,
  * group, and level. Modifiers that affected the translation and
  * are thus unavailable for application use are returned in
  * @consumed_modifiers.
- * See <xref linkend="key-group-explanation"/> for an explanation of
+ * See [Groups][key-group-explanation] for an explanation of
  * groups and levels. The @effective_group is the group that was
  * actually used for the translation; some keys such as Enter are not
  * affected by the active keyboard group. The @level is derived from

gdk/gdkpango.c

@@ -119,7 +119,7 @@
  * g_object_unref (context);
  * ]|
  *
- * ## Output of <xref linkend="rotated-example"/>
+ * ## Output of the [example][rotated-example] above.
  *
  * ![](rotated-text.png)
  */

gdk/gdkwindow.h

@@ -67,7 +67,7 @@ typedef enum
  *  #GtkMenu)
  * @GDK_WINDOW_FOREIGN: foreign window (see gdk_window_foreign_new())
  * @GDK_WINDOW_OFFSCREEN: offscreen window (see
- *  <xref linkend="OFFSCREEN-WINDOWS"/>). Since 2.18
+ *  [Offscreen Windows][OFFSCREEN-WINDOWS]). Since 2.18
  *
  * Describes the kind of window.
  */

gtk/deprecated/gtkaction.c

@@ -618,7 +618,7 @@ gtk_action_buildable_get_name (GtkBuildable *buildable)
  * Creates a new #GtkAction object. To add the action to a
  * #GtkActionGroup and set the accelerator for the action,
  * call gtk_action_group_add_action_with_accel().
- * See <xref linkend="XML-UI"/> for information on allowed action
+ * See the [UI Definition section][XML-UI] for information on allowed action
  * names.
  *
  * Return value: a new #GtkAction

gtk/deprecated/gtkhbox.c

@@ -53,7 +53,7 @@ G_GNUC_BEGIN_IGNORE_DEPRECATIONS
  * If you don't need first-child or last-child styling, and want your code
  * to be future-proof, the recommendation is to switch to #GtkGrid instead
  * of nested boxes. For more information about migrating to #GtkGrid,
- * see <xref linkend="gtk-migrating-GtkGrid"/>
+ * see [Migrating from other containers to GtkGrid][gtk-migrating-GtkGrid].
  */
 
 
@@ -85,7 +85,7 @@ gtk_hbox_init (GtkHBox *hbox)
  * Deprecated: 3.2: You can use gtk_box_new() with %GTK_ORIENTATION_HORIZONTAL instead,
  *   which is a quick and easy change. But the recommendation is to switch to
  *   #GtkGrid, since #GtkBox is going to go away eventually.
- *   See <xref linkend="gtk-migrating-GtkGrid"/>.
+ *   See [Migrating from other containers to GtkGrid][gtk-migrating-GtkGrid].
  */
 GtkWidget *
 gtk_hbox_new (gboolean homogeneous,

gtk/deprecated/gtkrc.c

@@ -907,8 +907,7 @@ gtk_rc_get_theme_dir (void)
  *
  * Returns a directory in which GTK+ looks for theme engines.
  * For full information about the search for theme engines,
- * see the docs for `GTK_PATH` in
- * <xref linkend="gtk-running"/>.
+ * see the docs for `GTK_PATH` in [Running GTK+ Applications][gtk-running].
  *
  * return value: (type filename): the directory. (Must be freed with g_free())
  *

gtk/deprecated/gtkstock.c

@@ -49,8 +49,7 @@ Prebuilt common menu/toolbar items and corresponding icons
  * Each stock ID can be associated with a #GtkStockItem, which contains
  * the user-visible label, keyboard accelerator, and translation domain
  * of the menu or toolbar item; and/or with an icon stored in a
- * #GtkIconFactory. See [GtkIconFactory][gtk3-Themeable-Stock-Images] for
- * more information on stock icons. The connection between a
+ * #GtkIconFactory. The connection between a
  * #GtkStockItem and stock icons is purely conventional (by virtue of
  * using the same stock ID); it's possible to register a stock item but
  * no icon, and vice versa. Stock icons may have a RTL variant which gets

gtk/deprecated/gtkvbox.c

@@ -58,7 +58,7 @@ G_GNUC_BEGIN_IGNORE_DEPRECATIONS
  * If you don't need first-child or last-child styling and want your code
  * to be future-proof, the recommendation is to switch to #GtkGrid instead
  * of nested boxes. For more information about migrating to #GtkGrid,
- * see <xref linkend="gtk-migrating-GtkGrid"/>.
+ * see [Migrating from other containers to GtkGrid][gtk-migrating-GtkGrid].
  */
 
 G_DEFINE_TYPE (GtkVBox, gtk_vbox, GTK_TYPE_BOX)
@@ -89,7 +89,7 @@ gtk_vbox_init (GtkVBox *vbox)
  * Deprecated: 3.2: You can use gtk_box_new() with %GTK_ORIENTATION_VERTICAL instead,
  *   which is a quick and easy change. But the recommendation is to switch to
  *   #GtkGrid, since #GtkBox is going to go away eventually.
- *   See <xref linkend="gtk-migrating-GtkGrid"/>.
+ *   See [Migrating from other containers to GtkGrid][gtk-migrating-GtkGrid].
  */
 GtkWidget *
 gtk_vbox_new (gboolean homogeneous,

gtk/gtkcssprovider.c

@@ -157,7 +157,8 @@
  * character.
  *
  * Refer to the documentation of individual widgets to learn which
- * style classes they define and see <xref linkend="gtkstylecontext-classes"/>
+ * style classes they define and see
+ * [Style Classes and Regions][gtkstylecontext-classes]
  * for a list of all style classes used by GTK+ widgets.
  *
  * Note that there is some ambiguity in the selector syntax when it comes
@@ -192,7 +193,8 @@
  *
  * Refer to the documentation of individual widgets to learn which
  * regions and pseudo-classes they define and see
- * <xref linkend="gtkstylecontext-classes"/> for a list of all regions
+ * [Style Classes and Regions][gtkstylecontext-classes]
+ * for a list of all regions
  * used by GTK+ widgets.
  *
  * An example for regions in selectors:

gtk/gtkfilechooser.c

@@ -92,7 +92,7 @@
  * flag that indicates whether your callback could successfully
  * generate a preview.
  *
- * ## An example for using a preview widget ## {#gtkfilechooser-preview}
+ * ## Example: Using a Preview Widget ## {#gtkfilechooser-preview}
  * |[<!-- language="C" -->
  * {
  *   GtkImage *preview;
@@ -253,7 +253,8 @@ gtk_file_chooser_default_init (GtkFileChooserInterface *iface)
    * must call gtk_file_chooser_set_preview_widget_active() to inform the file
    * chooser about whether the preview was generated successfully or not.
    *
-   * Please see the example code in <xref linkend="gtkfilechooser-preview"/>.
+   * Please see the example code in
+   * [Using a Preview Widget][gtkfilechooser-preview].
    *
    * See also: gtk_file_chooser_set_preview_widget(),
    * gtk_file_chooser_set_preview_widget_active(),

gtk/gtkicontheme.c

@@ -76,12 +76,12 @@
  * their icons, but more additional application themes can be
  * installed as operating system vendors and users choose.
  *
- * Named icons are similar to the <xref linkend="gtk3-Themeable-Stock-Images"/>
- * facility, and the distinction between the two may be a bit confusing.
+ * Named icons are similar to the deprecated [Stock Items][gtkstock],
+ * and the distinction between the two may be a bit confusing.
  * A few things to keep in mind:
  * 
  * - Stock images usually are used in conjunction with
- *   <xref linkend="gtk3-Stock-Items"/>, such as %GTK_STOCK_OK or
+ *   [Stock Items][gtkstock], such as %GTK_STOCK_OK or
  *   %GTK_STOCK_OPEN. Named icons are easier to set up and therefore
  *   are more useful for new icons that an application wants to
  *   add, such as application icons or window icons.

gtk/gtkimage.h

@@ -52,8 +52,7 @@ typedef struct _GtkImageClass         GtkImageClass;
  * GtkImageType:
  * @GTK_IMAGE_EMPTY: there is no image displayed by the widget
  * @GTK_IMAGE_PIXBUF: the widget contains a #GdkPixbuf
- * @GTK_IMAGE_STOCK: the widget contains a stock icon name (see
- *  <xref linkend="gtk3-Stock-Items"/>)
+ * @GTK_IMAGE_STOCK: the widget contains a [stock item name][gtkstock]
  * @GTK_IMAGE_ICON_SET: the widget contains a #GtkIconSet
  * @GTK_IMAGE_ANIMATION: the widget contains a #GdkPixbufAnimation
  * @GTK_IMAGE_ICON_NAME: the widget contains a named icon.

gtk/gtkimcontext.c

@@ -35,7 +35,8 @@
  *
  * The default input method can be set programmatically via the 
  * #GtkSettings:gtk-im-module GtkSettings property. Alternatively, you may set 
- * the GTK_IM_MODULE environment variable as documented in #gtk-running.
+ * the GTK_IM_MODULE environment variable as documented in
+ * [Running GTK+ Applications][gtk-running].
  *
  * The #GtkEntry #GtkEntry:im-module and #GtkTextView #GtkTextView:im-module 
  * properties may also be used to set input methods for specific widget 

gtk/gtkstylecontext.c

@@ -75,7 +75,7 @@
  * #GtkSettings:gtk-theme-name setting or a hierarchy change in the rendered
  * widget.
  *
- * # Transition animations
+ * # Transition Animations
  *
  * #GtkStyleContext has built-in support for state change transitions.
  * Note that these animations respect the #GtkSettings:gtk-enable-animations
@@ -172,10 +172,11 @@
  * special value, in this case, the whole widget area will be updated
  * by the animation.
  *
- * # Style classes and regions # {#gtkstylecontext-classes}
+ * # Style Classes and Regions # {#gtkstylecontext-classes}
  *
  * Widgets can add style classes to their context, which can be used
- * to associate different styles by class (see <xref linkend="gtkcssprovider-selectors"/>).
+ * to associate different styles by class
+ * (see [Selectors][gtkcssprovider-selectors]).
  * Theme engines can also use style classes to vary their rendering.
  *
  * Widgets can also add regions with flags to their context.

gtk/gtkwidget.c

@@ -3312,7 +3312,8 @@ G_GNUC_END_IGNORE_DEPRECATIONS
    * menu. This usually happens through the standard key binding mechanism;
    * by pressing a certain key while a widget is focused, the user can cause
    * the widget to pop up a menu.  For example, the #GtkEntry widget creates
-   * a menu with clipboard commands. See <xref linkend="checklist-popup-menu"/>
+   * a menu with clipboard commands. See the
+   * [Popup Menu Migration Checklist][checklist-popup-menu]
    * for an example of how to use this signal.
    *
    * Returns: %TRUE if a menu was activated

gtk/gtkwidget.h

@@ -77,7 +77,8 @@ typedef struct _GtkWidgetAuxInfo       GtkWidgetAuxInfo;
  *
  * A #GtkAllocation-struct of a widget represents region
  * which has been allocated to the widget by its parent. It is a subregion
- * of its parents allocation. See <xref linkend="geometry-management"/> for
+ * of its parents allocation. See
+ * [GtkWidget's geometry management section][geometry-management] for
  * more information.
  */
 typedef 	GdkRectangle	   GtkAllocation;
@@ -116,7 +117,8 @@ typedef gboolean (*GtkTickCallback) (GtkWidget     *widget,
  * @height: the widget's desired height
  *
  * A #GtkRequisition-struct represents the desired size of a widget. See
- * <xref linkend="geometry-management"/> for more information.
+ * [GtkWidget's geometry management section][geometry-management] for
+ * more information.
  */
 struct _GtkRequisition
 {