docs: use links instead of <xref>

13 files changed, 30 insertions, 25 deletions

diff --git a/gtk/deprecated/gtkaction.c b/gtk/deprecated/gtkaction.c
index e0b1367f5a..b9630ae2b3 100644
--- a/gtk/deprecated/gtkaction.c
+++ b/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
diff --git a/gtk/deprecated/gtkhbox.c b/gtk/deprecated/gtkhbox.c
index 5c6b3cad6d..77ede7f239 100644
--- a/gtk/deprecated/gtkhbox.c
+++ b/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,
diff --git a/gtk/deprecated/gtkrc.c b/gtk/deprecated/gtkrc.c
index c4494dff55..8c27040b3e 100644
--- a/gtk/deprecated/gtkrc.c
+++ b/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())
  *
diff --git a/gtk/deprecated/gtkstock.c b/gtk/deprecated/gtkstock.c
index 8c00b4d3f0..245d213c4c 100644
--- a/gtk/deprecated/gtkstock.c
+++ b/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
diff --git a/gtk/deprecated/gtkvbox.c b/gtk/deprecated/gtkvbox.c
index 6a95410ae8..c28f6387b6 100644
--- a/gtk/deprecated/gtkvbox.c
+++ b/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,
diff --git a/gtk/gtkcssprovider.c b/gtk/gtkcssprovider.c
index eeb3e07ed7..04cfab3457 100644
--- a/gtk/gtkcssprovider.c
+++ b/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:
diff --git a/gtk/gtkfilechooser.c b/gtk/gtkfilechooser.c
index d088f0b375..90bc88a3a2 100644
--- a/gtk/gtkfilechooser.c
+++ b/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(),
diff --git a/gtk/gtkicontheme.c b/gtk/gtkicontheme.c
index a89683cdf8..08d3aba862 100644
--- a/gtk/gtkicontheme.c
+++ b/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.
diff --git a/gtk/gtkimage.h b/gtk/gtkimage.h
index 18e26e25a6..3e18fa5eb6 100644
--- a/gtk/gtkimage.h
+++ b/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.
diff --git a/gtk/gtkimcontext.c b/gtk/gtkimcontext.c
index 4b17b2aea6..e2c3257a19 100644
--- a/gtk/gtkimcontext.c
+++ b/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 
diff --git a/gtk/gtkstylecontext.c b/gtk/gtkstylecontext.c
index 5cabff2b7f..4a63c9e928 100644
--- a/gtk/gtkstylecontext.c
+++ b/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.
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index a599b13af0..e882bb2b88 100644
--- a/gtk/gtkwidget.c
+++ b/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
diff --git a/gtk/gtkwidget.h b/gtk/gtkwidget.h
index 20cdf462db..31a0a5195f 100644
--- a/gtk/gtkwidget.h
+++ b/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
 {