docs: Use markup for links

65 files changed, 262 insertions, 262 deletions

diff --git a/gdk/gdkcairo.c b/gdk/gdkcairo.c
index 78003c732d..d63d11650f 100644
--- a/gdk/gdkcairo.c
+++ b/gdk/gdkcairo.c
@@ -28,7 +28,7 @@
  * @Short_description: Functions to support using cairo
  * @Title: Cairo Interaction
  *
- * <link href="http://cairographics.org">Cairo</link> is a graphics
+ * [Cairo](http://cairographics.org) is a graphics
  * library that supports vector graphics and image compositing that
  * can be used with GDK. GTK+ does all of its drawing using cairo.
  *
diff --git a/gdk/gdkdevice.h b/gdk/gdkdevice.h
index 0633c0d0e4..f9f853d6a4 100644
--- a/gdk/gdkdevice.h
+++ b/gdk/gdkdevice.h
@@ -115,7 +115,7 @@ typedef enum
  * @GDK_DEVICE_TYPE_FLOATING: Device is a physical device, currently not attached to
  *                            any virtual device.
  *
- * Indicates the device type. See <link linkend="GdkDeviceManager.description">above</link>
+ * Indicates the device type. See [above][GdkDeviceManager.description]
  * for more information about the meaning of these device types.
  */
 typedef enum {
diff --git a/gdk/gdkdnd.c b/gdk/gdkdnd.c
index ced7d537f7..0a7636dab8 100644
--- a/gdk/gdkdnd.c
+++ b/gdk/gdkdnd.c
@@ -41,7 +41,7 @@
  *
  * GTK+ provides a higher level abstraction based on top of these functions,
  * and so they are not normally needed in GTK+ applications.
- * See the <link linkend="gtk3-Drag-and-Drop">Drag and Drop</link> section of
+ * See the [Drag and Drop][gtk3-Drag-and-Drop] section of
  * the GTK+ documentation for more information.
  */
 
diff --git a/gdk/gdkevents.c b/gdk/gdkevents.c
index 1dc216aa7b..e191739aa5 100644
--- a/gdk/gdkevents.c
+++ b/gdk/gdkevents.c
@@ -35,7 +35,7 @@
  * SECTION:events
  * @Short_description: Functions for handling events from the window system
  * @Title: Events
- * @See_also: <link linkend="gdk3-Event-Structures">Event Structures</link>
+ * @See_also: [Event Structures][gdk3-Event-Structures]
  *
  * This section describes functions dealing with events from the window
  * system.
@@ -43,7 +43,7 @@
  * In GTK+ applications the events are handled automatically in
  * gtk_main_do_event() and passed on to the appropriate widgets, so these
  * functions are rarely needed. Though some of the fields in the
- * <link linkend="gdk3-Event-Structures">Event Structures</link> are useful.
+ * [Event Structures][gdk3-Event-Structures] are useful.
  */
 
 
diff --git a/gdk/gdkevents.h b/gdk/gdkevents.h
index 458e550bc6..a490548a7f 100644
--- a/gdk/gdkevents.h
+++ b/gdk/gdkevents.h
@@ -56,7 +56,7 @@ G_BEGIN_DECLS
  * GDK_PRIORITY_EVENTS:
  *
  * This is the priority that events from the X server are given in the
- * <link linkend="glib-The-Main-Event-Loop">GLib Main Loop</link>.
+ * [GLib Main Loop][glib-The-Main-Event-Loop].
  */
 #define GDK_PRIORITY_EVENTS	(G_PRIORITY_DEFAULT)
 
@@ -65,7 +65,7 @@ G_BEGIN_DECLS
  *
  * This is the priority that the idle handler processing window updates
  * is given in the
- * <link linkend="glib-The-Main-Event-Loop">GLib Main Loop</link>.
+ * [GLib Main Loop][glib-The-Main-Event-Loop].
  */
 #define GDK_PRIORITY_REDRAW     (G_PRIORITY_HIGH_IDLE + 20)
 
diff --git a/gdk/gdkpango.c b/gdk/gdkpango.c
index e95d8cecc8..cff8690493 100644
--- a/gdk/gdkpango.c
+++ b/gdk/gdkpango.c
@@ -44,8 +44,8 @@
  * can set the text and attributes of it with Pango functions like
  * pango_layout_set_text() and get its size with pango_layout_get_size().
  * (Note that Pango uses a fixed point system internally, so converting
- * between Pango units and pixels using <link
- * linkend="PANGO-SCALE-CAPS">PANGO_SCALE</link> or the PANGO_PIXELS() macro.)
+ * between Pango units and pixels using [PANGO_SCALE][PANGO-SCALE-CAPS]
+ * or the PANGO_PIXELS() macro.)
  *
  * 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().
diff --git a/gdk/gdkselection.c b/gdk/gdkselection.c
index 326cfdebfa..1d7c2b6cc4 100644
--- a/gdk/gdkselection.c
+++ b/gdk/gdkselection.c
@@ -48,7 +48,7 @@
  * retrieved by requesting the special target `TARGETS`. When
  * a selection is retrieved, the data is accompanied by a type (an atom), and
  * a format (an integer, representing the number of bits per item).
- * See <link linkend="gdk3-Properties-and-Atoms">Properties and Atoms</link>
+ * See [Properties and Atoms][gdk3-Properties-and-Atoms]
  * for more information.
  *
  * The functions in this section only contain the lowlevel parts of the
diff --git a/gtk/deprecated/gtkaction.c b/gtk/deprecated/gtkaction.c
index b27e71bd96..e0b1367f5a 100644
--- a/gtk/deprecated/gtkaction.c
+++ b/gtk/deprecated/gtkaction.c
@@ -63,9 +63,9 @@
  *
  * - sensitive (enabled/disabled)
  *
- * Apart from regular actions, there are <link linkend="GtkToggleAction">toggle
- * actions</link>, which can be toggled between two states and <link
- * linkend="GtkRadioAction">radio actions</link>, of which only one in a group
+ * Apart from regular actions, there are [toggle actions][GtkToggleAction],
+ * which can be toggled between two states and
+ * [radio actions][GtkRadioAction], of which only one in a group
  * can be in the “active” state. Other actions can be implemented as #GtkAction
  * subclasses.
  *
diff --git a/gtk/deprecated/gtkactiongroup.c b/gtk/deprecated/gtkactiongroup.c
index a2bde7bfb6..16dde2a70e 100644
--- a/gtk/deprecated/gtkactiongroup.c
+++ b/gtk/deprecated/gtkactiongroup.c
@@ -523,7 +523,7 @@ gtk_action_group_buildable_custom_tag_end (GtkBuildable *buildable,
  * @name: the name of the action group.
  *
  * Creates a new #GtkActionGroup object. The name of the action group
- * is used when associating <link linkend="Action-Accel">keybindings</link> 
+ * is used when associating [keybindings][Action-Accel] 
  * with the actions.
  *
  * Returns: the new #GtkActionGroup
diff --git a/gtk/deprecated/gtkgradient.c b/gtk/deprecated/gtkgradient.c
index 11cde72368..e8759e05e7 100644
--- a/gtk/deprecated/gtkgradient.c
+++ b/gtk/deprecated/gtkgradient.c
@@ -33,7 +33,7 @@
  *
  * GtkGradient is a boxed type that represents a gradient.
  * It is the result of parsing a
- * <link linkend="gtkcssprovider-gradients">gradient expression</link>.
+ * [gradient expression][gtkcssprovider-gradients].
  * To obtain the gradient represented by a GtkGradient, it has to
  * be resolved with gtk_gradient_resolve(), which replaces all
  * symbolic color references by the colors they refer to (in a given
diff --git a/gtk/deprecated/gtkrc.c b/gtk/deprecated/gtkrc.c
index 82a3abdede..c4494dff55 100644
--- a/gtk/deprecated/gtkrc.c
+++ b/gtk/deprecated/gtkrc.c
@@ -274,7 +274,7 @@
  *         it is searched in the directories of the currently open RC files.
  *
  *    GTK+ also tries to load a
- *         <link linkend="locale-specific-rc">locale-specific variant</link> of
+ *         [locale-specific variant][locale-specific-rc] of
  *         the included file.
  *
  * * `module_path path`
@@ -316,7 +316,7 @@
  *
  * * setting = value
  *
- *    Specifies a value for a <link linkend="GtkSettings">setting</link>.
+ *    Specifies a value for a [setting][GtkSettings].
  *         Note that settings in RC files are overwritten by system-wide settings
  *         (which are managed by an XSettings manager on X11).
  *
@@ -411,7 +411,7 @@
  *
  * * `class::property = value`
  *
- *         Sets a <link linkend="style-properties">style property</link> for a widget class.
+ *         Sets a [style property][style-properties] for a widget class.
  *
  * The colors and background pixmaps are specified as a function of the
  * state of the widget. The states are:
diff --git a/gtk/deprecated/gtkstock.c b/gtk/deprecated/gtkstock.c
index 78befcb1b0..8c00b4d3f0 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 <link
- * linkend="gtk3-Themeable-Stock-Images">GtkIconFactory</link> for
+ * #GtkIconFactory. See [GtkIconFactory][gtk3-Themeable-Stock-Images] for
  * more information on stock icons. 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
diff --git a/gtk/deprecated/gtksymboliccolor.c b/gtk/deprecated/gtksymboliccolor.c
index ef60974077..f156c6e8b8 100644
--- a/gtk/deprecated/gtksymboliccolor.c
+++ b/gtk/deprecated/gtksymboliccolor.c
@@ -36,7 +36,7 @@
  *
  * GtkSymbolicColor is a boxed type that represents a symbolic color.
  * It is the result of parsing a
- * <link linkend="gtkcssprovider-symbolic-colors">color expression</link>.
+ * [color expression][gtkcssprovider-symbolic-colors].
  * To obtain the color represented by a GtkSymbolicColor, it has to
  * be resolved with gtk_symbolic_color_resolve(), which replaces all
  * symbolic color references by the colors they refer to (in a given
diff --git a/gtk/deprecated/gtkuimanager.c b/gtk/deprecated/gtkuimanager.c
index 955068c41d..38cb16e03d 100644
--- a/gtk/deprecated/gtkuimanager.c
+++ b/gtk/deprecated/gtkuimanager.c
@@ -66,8 +66,7 @@
  * roughly described by the following DTD.
  *
  * > Do not confuse the GtkUIManager UI Definitions described here with
- * > the similarly named <link linkend="BUILDER-UI">GtkBuilder UI
- * > Definitions</link>.
+ * > the similarly named [GtkBuilder UI Definitions][BUILDER-UI].
  *
  * |[
  * <!ELEMENT ui          (menubar|toolbar|popup|accelerator)* >
@@ -1933,7 +1932,7 @@ add_ui_from_string (GtkUIManager *manager,
  * @length: the length of @buffer (may be -1 if @buffer is nul-terminated)
  * @error: return location for an error
  * 
- * Parses a string containing a <link linkend="XML-UI">UI definition</link> and 
+ * Parses a string containing a [UI definition][XML-UI] and 
  * merges it with the current contents of @manager. An enclosing &lt;ui&gt; 
  * element is added if it is missing.
  * 
@@ -1978,7 +1977,7 @@ gtk_ui_manager_add_ui_from_string (GtkUIManager *manager,
  * @filename: (type filename): the name of the file to parse 
  * @error: return location for an error
  * 
- * Parses a file containing a <link linkend="XML-UI">UI definition</link> and 
+ * Parses a file containing a [UI definition][XML-UI] and 
  * merges it with the current contents of @manager. 
  * 
  * Return value: The merge id for the merged UI. The merge id can be used
@@ -2015,7 +2014,7 @@ gtk_ui_manager_add_ui_from_file (GtkUIManager *manager,
  * @resource_path: the resource path of the file to parse
  * @error: return location for an error
  *
- * Parses a resource file containing a <link linkend="XML-UI">UI definition</link> and
+ * Parses a resource file containing a [UI definition][XML-UI] and
  * merges it with the current contents of @manager.
  *
  * Return value: The merge id for the merged UI. The merge id can be used
@@ -3341,7 +3340,7 @@ gtk_ui_manager_buildable_custom_tag_end (GtkBuildable *buildable,
  * gtk_ui_manager_get_ui:
  * @manager: a #GtkUIManager
  * 
- * Creates a <link linkend="XML-UI">UI definition</link> of the merged UI.
+ * Creates a [UI definition][XML-UI] of the merged UI.
  * 
  * Return value: A newly allocated string containing an XML representation of 
  * the merged UI.
diff --git a/gtk/gtkaccelmap.c b/gtk/gtkaccelmap.c
index 2cc38cb5c1..c5819d564e 100644
--- a/gtk/gtkaccelmap.c
+++ b/gtk/gtkaccelmap.c
@@ -65,8 +65,8 @@
  * path may look like: “&lt;Gimp-Toolbox&gt;/File/Dialogs/Tool Options...”.
  *
  * All accelerators are stored inside one global #GtkAccelMap that can
- * be obtained using gtk_accel_map_get(). See <link
- * linkend="monitoring-changes">Monitoring changes</link> for additional
+ * be obtained using gtk_accel_map_get(). See
+ * [Monitoring changes][monitoring-changes] for additional
  * details.
  *
  * # Manipulating accelerators
diff --git a/gtk/gtkappchooser.c b/gtk/gtkappchooser.c
index 4ee53e8692..dae884c180 100644
--- a/gtk/gtkappchooser.c
+++ b/gtk/gtkappchooser.c
@@ -66,7 +66,7 @@ gtk_app_chooser_default_init (GtkAppChooserIface *iface)
    *
    * The content type of the #GtkAppChooser object.
    *
-   * See <link linkend="gio-GContentType">GContentType</link>
+   * See [GContentType][gio-GContentType]
    * for more information about content types.
    */
   pspec = g_param_spec_string ("content-type",
diff --git a/gtk/gtkassistant.c b/gtk/gtkassistant.c
index 31566b97bd..7ef9d4bf8d 100644
--- a/gtk/gtkassistant.c
+++ b/gtk/gtkassistant.c
@@ -32,10 +32,10 @@
  *
  * The design of GtkAssistant is that it controls what buttons to show
  * and to make sensitive, based on what it knows about the page sequence
- * and the <link linkend="GtkAssistantPageType">type</link> of each page,
+ * and the [type][GtkAssistantPageType] of each page,
  * in addition to state information like the page
- * <link linkend="gtk-assistant-set-page-complete">completion</link>
- * and <link linkend="gtk-assistant-commit">committed</link> status.
+ * [completion][gtk-assistant-set-page-complete]
+ * and [committed][gtk-assistant-commit] status.
  *
  * If you have a case that doesn't quite fit in #GtkAssistants way of
  * handling buttons, you can use the #GTK_ASSISTANT_PAGE_CUSTOM page
diff --git a/gtk/gtkbindings.c b/gtk/gtkbindings.c
index 15dbb12f27..772038448c 100644
--- a/gtk/gtkbindings.c
+++ b/gtk/gtkbindings.c
@@ -52,12 +52,12 @@
  * A CSS file binding consists of a 'binding-set' definition and a match
  * statement to apply the binding set to specific widget types. Details
  * on the matching mechanism are described under
- * <link linkend="gtkcssprovider-selectors">Selectors</link>
+ * [Selectors][gtkcssprovider-selectors]
  * in the #GtkCssProvider documentation. Inside the binding set
  * definition, key combinations are bound to one or more specific
  * signal emissions on the target widget. Key combinations are strings
  * consisting of an optional #GdkModifierType name and
- * <link linkend="gdk3-Keyboard-Handling">key names</link>
+ * [key names][gdk3-Keyboard-Handling]
  * such as those defined in `gdk/gdkkeysyms.h`
  * or returned from gdk_keyval_name(), they have to be parsable by
  * gtk_accelerator_parse(). Specifications of signal emissions consist
@@ -87,7 +87,7 @@
  * it provides. Because custom bindings set up in CSS files take
  * precedence over the default bindings shipped with GTK+, overriding
  * existing bindings as demonstrated in
- * <link linkend="gtk-bindings-install">Installing a key binding</link>
+ * [Installing a key binding][gtk-bindings-install]
  * works as expected. The same mechanism can not be used to “unbind”
  * existing bindings, however.
  *
diff --git a/gtk/gtkbuildable.c b/gtk/gtkbuildable.c
index 38ee81addd..6aff915ad6 100644
--- a/gtk/gtkbuildable.c
+++ b/gtk/gtkbuildable.c
@@ -22,7 +22,7 @@
  * @Title: GtkBuildable
  *
  * GtkBuildable allows objects to extend and customize their deserialization
- * from <link linkend="BUILDER-UI">GtkBuilder UI descriptions</link>.
+ * from [GtkBuilder UI descriptions][BUILDER-UI].
  * The interface includes methods for setting names and properties of objects, 
  * parsing custom tags and constructing child objects.
  *
@@ -84,7 +84,7 @@ gtk_buildable_set_name (GtkBuildable *buildable,
  * Gets the name of the @buildable object. 
  * 
  * #GtkBuilder sets the name based on the
- * <link linkend="BUILDER-UI">GtkBuilder UI definition</link> 
+ * [GtkBuilder UI definition][BUILDER-UI] 
  * used to construct the @buildable.
  *
  * Returns: the name set with gtk_buildable_set_name()
@@ -173,7 +173,7 @@ gtk_buildable_set_buildable_property (GtkBuildable *buildable,
  * @builder: a #GtkBuilder
  *
  * Called when the builder finishes the parsing of a 
- * <link linkend="BUILDER-UI">GtkBuilder UI definition</link>. 
+ * [GtkBuilder UI definition][BUILDER-UI]. 
  * Note that this will be called once for each time 
  * gtk_builder_add_from_file() or gtk_builder_add_from_string() 
  * is called on a builder.
diff --git a/gtk/gtkbuilder.c b/gtk/gtkbuilder.c
index e2c183b1fa..b2893e9a9d 100644
--- a/gtk/gtkbuilder.c
+++ b/gtk/gtkbuilder.c
@@ -64,7 +64,7 @@
  * “GtkBuilder UI definitions” or just
  * “UI definitions” if the context is clear.
  * Do not confuse GtkBuilder UI Definitions with
- * <link linkend="XML-UI">GtkUIManager UI Definitions</link>, which
+ * [GtkUIManager UI Definitions][XML-UI], which
  * are more limited in scope. It is common to use `.ui`
  * as the filename extension for files containing GtkBuilder UI
  * definitions.
@@ -946,11 +946,11 @@ gtk_builder_new (void)
  * @filename: the name of the file to parse
  * @error: (allow-none): return location for an error, or %NULL
  *
- * Parses a file containing a <link linkend="BUILDER-UI">GtkBuilder 
- * UI definition</link> and merges it with the current contents of @builder.
+ * Parses a file containing a [GtkBuilder UI definition][BUILDER-UI]
+ * and merges it with the current contents of @builder.
  *
  * Most users will probably want to use gtk_builder_new_from_file().
- * 
+ *
  * Upon errors 0 will be returned and @error will be assigned a
  * #GError from the #GTK_BUILDER_ERROR, #G_MARKUP_ERROR or #G_FILE_ERROR 
  * domain.
@@ -1015,9 +1015,9 @@ gtk_builder_add_from_file (GtkBuilder   *builder,
  * @object_ids: (array zero-terminated=1) (element-type utf8): nul-terminated array of objects to build
  * @error: (allow-none): return location for an error, or %NULL
  *
- * Parses a file containing a <link linkend="BUILDER-UI">GtkBuilder 
- * UI definition</link> building only the requested objects and merges
- * them with the current contents of @builder. 
+ * Parses a file containing a [GtkBuilder UI definition][BUILDER-UI]
+ * building only the requested objects and merges
+ * them with the current contents of @builder.
  *
  * Upon errors 0 will be returned and @error will be assigned a
  * #GError from the #GTK_BUILDER_ERROR, #G_MARKUP_ERROR or #G_FILE_ERROR 
@@ -1123,8 +1123,8 @@ _gtk_builder_extend_with_template (GtkBuilder    *builder,
  * @resource_path: the path of the resource file to parse
  * @error: (allow-none): return location for an error, or %NULL
  *
- * Parses a resource file containing a <link linkend="BUILDER-UI">GtkBuilder
- * UI definition</link> and merges it with the current contents of @builder.
+ * Parses a resource file containing a [GtkBuilder UI definition][BUILDER-UI]
+ * and merges it with the current contents of @builder.
  *
  * Most users will probably want to use gtk_builder_new_from_resource().
  *
@@ -1201,8 +1201,8 @@ gtk_builder_add_from_resource (GtkBuilder   *builder,
  * @object_ids: (array zero-terminated=1) (element-type utf8): nul-terminated array of objects to build
  * @error: (allow-none): return location for an error, or %NULL
  *
- * Parses a resource file containing a <link linkend="BUILDER-UI">GtkBuilder
- * UI definition</link> building only the requested objects and merges
+ * Parses a resource file containing a [GtkBuilder UI definition][BUILDER-UI]
+ * building only the requested objects and merges
  * them with the current contents of @builder.
  *
  * Upon errors 0 will be returned and @error will be assigned a
@@ -1279,8 +1279,8 @@ gtk_builder_add_objects_from_resource (GtkBuilder   *builder,
  * @length: the length of @buffer (may be -1 if @buffer is nul-terminated)
  * @error: (allow-none): return location for an error, or %NULL
  *
- * Parses a string containing a <link linkend="BUILDER-UI">GtkBuilder 
- * UI definition</link> and merges it with the current contents of @builder. 
+ * Parses a string containing a [GtkBuilder UI definition][BUILDER-UI]
+ * and merges it with the current contents of @builder.
  *
  * Most users will probably want to use gtk_builder_new_from_string().
  *
@@ -1335,8 +1335,8 @@ gtk_builder_add_from_string (GtkBuilder   *builder,
  * @object_ids: (array zero-terminated=1) (element-type utf8): nul-terminated array of objects to build
  * @error: (allow-none): return location for an error, or %NULL
  *
- * Parses a string containing a <link linkend="BUILDER-UI">GtkBuilder 
- * UI definition</link> building only the requested objects and merges
+ * Parses a string containing a [GtkBuilder UI definition][BUILDER-UI]
+ * building only the requested objects and merges
  * them with the current contents of @builder. 
  *
  * Upon errors 0 will be returned and @error will be assigned a
@@ -2394,7 +2394,7 @@ gtk_builder_lookup_callback_symbol (GtkBuilder    *builder,
  * gtk_builder_new_from_file:
  * @filename: filename of user interface description file
  *
- * Builds the <link linkend="BUILDER-UI">GtkBuilder UI definition</link>
+ * Builds the [GtkBuilder UI definition][BUILDER-UI]
  * in the file @filename.
  *
  * If there is an error opening the file or parsing the description then
@@ -2422,7 +2422,7 @@ gtk_builder_new_from_file (const gchar *filename)
  * gtk_builder_new_from_resource:
  * @resource_path: a #GResource resource path
  *
- * Builds the <link linkend="BUILDER-UI">GtkBuilder UI definition</link>
+ * Builds the [GtkBuilder UI definition][BUILDER-UI]
  * at @resource_path.
  *
  * If there is an error locating the resurce or parsing the description
@@ -2450,8 +2450,8 @@ gtk_builder_new_from_resource (const gchar *resource_path)
  * @string: a user interface (XML) description
  * @length: the length of @string, or -1
  *
- * Builds the user interface described by @string (in the <link
- * linkend="BUILDER-UI">GtkBuilder UI definition</link> format).
+ * Builds the user interface described by @string (in the
+ * [GtkBuilder UI definition][BUILDER-UI] format).
  *
  * If @string is %NULL-terminated then @length should be -1.  If @length
  * is not -1 then it is the length of @string.
diff --git a/gtk/gtkcellarea.c b/gtk/gtkcellarea.c
index e7f0f7ff9e..1c41e21bee 100644
--- a/gtk/gtkcellarea.c
+++ b/gtk/gtkcellarea.c
@@ -37,8 +37,9 @@
  *
  * # Requesting area sizes
  *
- * As outlined in <link linkend="geometry-management">GtkWidget's
- * geometry management section</link>, GTK+ uses a height-for-width
+ * As outlined in
+ * [GtkWidget's geometry management section][geometry-management],
+ * GTK+ uses a height-for-width
  * geometry management system to compute the sizes of widgets and user
  * interfaces. #GtkCellArea uses the same semantics to calculate the
  * size of an area for an arbitrary number of #GtkTreeModel rows.
@@ -319,7 +320,7 @@
  *
  * The #GtkCellArea introduces cell properties for #GtkCellRenderers
  * in very much the same way that #GtkContainer introduces
- * <link linkend="child-properties">child properties</link>
+ * [child properties][child-properties]
  * for #GtkWidgets. This provides some general interfaces for defining
  * the relationship cell areas have with their cells. For instance in a
  * #GtkCellAreaBox a cell might “expand” and receive extra space when
diff --git a/gtk/gtkcelllayout.c b/gtk/gtkcelllayout.c
index 6b10b37d1e..f485fd81f7 100644
--- a/gtk/gtkcelllayout.c
+++ b/gtk/gtkcelllayout.c
@@ -59,7 +59,7 @@
  *
  * Furthermore for implementations of GtkCellLayout that use a
  * #GtkCellArea to lay out cells (all GtkCellLayouts in GTK+ use
- * a GtkCellArea) <link linkend="cell-properties">cell properties</link>
+ * a GtkCellArea) [cell properties][cell-properties]
  * can also be defined in the format by specifying the custom
  * &lt;cell-packing&gt; attribute which can contain multiple
  * &lt;property&gt; elements defined in the normal way.
diff --git a/gtk/gtkcellview.c b/gtk/gtkcellview.c
index 705b9ed9f5..d30f6d2f6a 100644
--- a/gtk/gtkcellview.c
+++ b/gtk/gtkcellview.c
@@ -1019,8 +1019,7 @@ gtk_cell_view_new_with_text (const gchar *text)
  *
  * Creates a new #GtkCellView widget, adds a #GtkCellRendererText 
  * to it, and makes it show @markup. The text can be
- * marked up with the <link linkend="PangoMarkupFormat">Pango text 
- * markup language</link>.
+ * marked up with the [Pango text markup language][PangoMarkupFormat].
  *
  * Return value: A newly created #GtkCellView widget.
  *
diff --git a/gtk/gtkcombobox.c b/gtk/gtkcombobox.c
index c887468474..5a33a01cd3 100644
--- a/gtk/gtkcombobox.c
+++ b/gtk/gtkcombobox.c
@@ -550,7 +550,7 @@ gtk_combo_box_class_init (GtkComboBoxClass *klass)
    * @scroll_type: a #GtkScrollType
    *
    * The ::move-active signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted to move the active selection.
    *
    * Since: 2.12
@@ -570,7 +570,7 @@ gtk_combo_box_class_init (GtkComboBoxClass *klass)
    * @widget: the object that received the signal
    *
    * The ::popup signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted to popup the combo box list.
    *
    * The default binding for this signal is Alt+Down.
@@ -590,7 +590,7 @@ gtk_combo_box_class_init (GtkComboBoxClass *klass)
    * @button: the object which received the signal
    *
    * The ::popdown signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted to popdown the combo box list.
    *
    * The default bindings for this signal are Alt+Up and Escape.
diff --git a/gtk/gtkcontainer.c b/gtk/gtkcontainer.c
index d5e7382025..202668c9d2 100644
--- a/gtk/gtkcontainer.c
+++ b/gtk/gtkcontainer.c
@@ -177,7 +177,7 @@
  * that the container adds. Then vertical expand space should be added where appropriate and available
  * and the container should go on to actually allocating the child widgets.
  *
- * See <link linkend="geometry-management">GtkWidget's geometry management section</link>
+ * See [GtkWidget's geometry management section][geometry-management]
  * to learn more about implementing height-for-width geometry management for widgets.
  *
  * # Child properties
@@ -802,7 +802,7 @@ gtk_container_child_type (GtkContainer *container)
  *     the class of @container
  *
  * Emits a #GtkWidget::child-notify signal for the
- * <link linkend="child-properties">child property</link>
+ * [child property][child-properties]
  * @child_property on widget.
  *
  * This is an analogue of g_object_notify() for child properties.
diff --git a/gtk/gtkdialog.c b/gtk/gtkdialog.c
index 0093c6f4d4..652be99304 100644
--- a/gtk/gtkdialog.c
+++ b/gtk/gtkdialog.c
@@ -502,7 +502,7 @@ gtk_dialog_class_init (GtkDialogClass *class)
    * GtkDialog::close:
    *
    * The ::close signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted when the user uses a keybinding to close
    * the dialog.
    *
diff --git a/gtk/gtkdnd.c b/gtk/gtkdnd.c
index 7fdb664964..1c864ffa4a 100644
--- a/gtk/gtkdnd.c
+++ b/gtk/gtkdnd.c
@@ -61,7 +61,7 @@
  *
  * As well as the functions listed here, applications
  * may need to use some facilities provided for
- * <link linkend="gtk3-Selections">Selections</link>.
+ * [Selections][gtk3-Selections].
  * Also, the Drag and Drop API makes use of signals
  * in the #GtkWidget class.
  */
diff --git a/gtk/gtkdrawingarea.c b/gtk/gtkdrawingarea.c
index 62c6c74612..ca5f34e246 100644
--- a/gtk/gtkdrawingarea.c
+++ b/gtk/gtkdrawingarea.c
@@ -99,8 +99,8 @@
  * gdk_window_invalidate_rect() are equally good ways to do this.
  * You'll then get a draw signal for the invalid region.
  *
- * The available routines for drawing are documented on the <link
- * linkend="gdk3-Cairo-Interaction">GDK Drawing Primitives</link> page
+ * The available routines for drawing are documented on the
+ * [GDK Drawing Primitives][gdk3-Cairo-Interaction] page
  * and the cairo documentation.
  *
  * To receive mouse events on a drawing area, you will need to enable
diff --git a/gtk/gtkentry.c b/gtk/gtkentry.c
index 4ca17c9a79..b10db21b94 100644
--- a/gtk/gtkentry.c
+++ b/gtk/gtkentry.c
@@ -1313,8 +1313,7 @@ gtk_entry_class_init (GtkEntryClass *class)
    * GtkEntry:primary-icon-tooltip-markup:
    * 
    * The contents of the tooltip on the primary icon, which is marked up
-   * with the <link linkend="PangoMarkupFormat">Pango text markup 
-   * language</link>.
+   * with the [Pango text markup language][PangoMarkupFormat].
    *
    * Also see gtk_entry_set_icon_tooltip_markup().
    *
@@ -1332,8 +1331,7 @@ gtk_entry_class_init (GtkEntryClass *class)
    * GtkEntry:secondary-icon-tooltip-markup:
    * 
    * The contents of the tooltip on the secondary icon, which is marked up
-   * with the <link linkend="PangoMarkupFormat">Pango text markup 
-   * language</link>.
+   * with the [Pango text markup language][PangoMarkupFormat].
    *
    * Also see gtk_entry_set_icon_tooltip_markup().
    *
@@ -1562,7 +1560,7 @@ gtk_entry_class_init (GtkEntryClass *class)
    * the Enter key.
    *
    * While this signal is used as a
-   * <link linkend="keybinding-signals">keybinding signal</link>,
+   * [keybinding signal][keybinding-signals],
    * it is also commonly used by applications to intercept
    * activation of entries.
    *
@@ -1586,7 +1584,7 @@ gtk_entry_class_init (GtkEntryClass *class)
    * @extend_selection: %TRUE if the move should extend the selection
    *
    * The ::move-cursor signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted when the user initiates a cursor movement.
    * If the cursor is not visible in @entry, this signal causes
    * the viewport to be moved instead.
@@ -1621,7 +1619,7 @@ gtk_entry_class_init (GtkEntryClass *class)
    * @string: the string to insert
    *
    * The ::insert-at-cursor signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted when the user initiates the insertion of a
    * fixed string at the cursor.
    *
@@ -1644,7 +1642,7 @@ gtk_entry_class_init (GtkEntryClass *class)
    * @count: the number of @type units to delete
    *
    * The ::delete-from-cursor signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted when the user initiates a text deletion.
    *
    * If the @type is %GTK_DELETE_CHARS, GTK+ deletes the selection
@@ -1671,7 +1669,7 @@ gtk_entry_class_init (GtkEntryClass *class)
    * @entry: the object which received the signal
    *
    * The ::backspace signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted when the user asks for it.
    *
    * The default bindings for this signal are
@@ -1691,7 +1689,7 @@ gtk_entry_class_init (GtkEntryClass *class)
    * @entry: the object which received the signal
    *
    * The ::cut-clipboard signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted to cut the selection to the clipboard.
    *
    * The default bindings for this signal are
@@ -1711,7 +1709,7 @@ gtk_entry_class_init (GtkEntryClass *class)
    * @entry: the object which received the signal
    *
    * The ::copy-clipboard signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted to copy the selection to the clipboard.
    *
    * The default bindings for this signal are
@@ -1731,7 +1729,7 @@ gtk_entry_class_init (GtkEntryClass *class)
    * @entry: the object which received the signal
    *
    * The ::paste-clipboard signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted to paste the contents of the clipboard
    * into the text view.
    *
@@ -1752,7 +1750,7 @@ gtk_entry_class_init (GtkEntryClass *class)
    * @entry: the object which received the signal
    *
    * The ::toggle-overwrite signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted to toggle the overwrite mode of the entry.
    *
    * The default bindings for this signal is Insert.
@@ -9114,7 +9112,7 @@ gtk_entry_get_icon_tooltip_markup (GtkEntry             *entry,
  *
  * Sets @tooltip as the contents of the tooltip for the icon at
  * the specified position. @tooltip is assumed to be marked up with
- * the <link linkend="PangoMarkupFormat">Pango text markup language</link>.
+ * the [Pango text markup language][PangoMarkupFormat].
  *
  * Use %NULL for @tooltip to remove an existing tooltip.
  *
diff --git a/gtk/gtkentrycompletion.c b/gtk/gtkentrycompletion.c
index 9e5e762dfa..869b64ebe0 100644
--- a/gtk/gtkentrycompletion.c
+++ b/gtk/gtkentrycompletion.c
@@ -415,8 +415,7 @@ gtk_entry_completion_class_init (GtkEntryCompletionClass *klass)
    * Determines whether the completions popup window will shown
    * for a single possible completion. You probably want to set
    * this to %FALSE if you are using
-   * <link linkend="GtkEntryCompletion--inline-completion">inline
-   * completion</link>.
+   * [inline completion][GtkEntryCompletion--inline-completion].
    *
    * Since: 2.8
    */
@@ -2161,8 +2160,7 @@ gtk_entry_completion_get_popup_set_width (GtkEntryCompletion *completion)
  *
  * Sets whether the completion popup window will appear even if there is
  * only a single match. You may want to set this to %FALSE if you
- * are using <link linkend="GtkEntryCompletion--inline-completion">inline
- * completion</link>.
+ * are using [inline completion][GtkEntryCompletion--inline-completion].
  *
  * Since: 2.8
  */
diff --git a/gtk/gtkexpander.c b/gtk/gtkexpander.c
index 6fa157f84c..270068fea3 100644
--- a/gtk/gtkexpander.c
+++ b/gtk/gtkexpander.c
@@ -1905,9 +1905,9 @@ gtk_expander_get_use_underline (GtkExpander *expander)
  * @expander: a #GtkExpander
  * @use_markup: %TRUE if the label's text should be parsed for markup
  *
- * Sets whether the text of the label contains markup in <link
- * linkend="PangoMarkupFormat">Pango's text markup
- * language</link>. See gtk_label_set_markup().
+ * Sets whether the text of the label contains markup in
+ * [Pango's text markup language][PangoMarkupFormat].
+ * See gtk_label_set_markup().
  *
  * Since: 2.4
  */
@@ -1939,8 +1939,8 @@ gtk_expander_set_use_markup (GtkExpander *expander,
  * @expander: a #GtkExpander
  *
  * Returns whether the label's text is interpreted as marked up with
- * the <link linkend="PangoMarkupFormat">Pango text markup
- * language</link>. See gtk_expander_set_use_markup().
+ * the [Pango text markup language][PangoMarkupFormat].
+ * See gtk_expander_set_use_markup().
  *
  * Return value: %TRUE if the label's text will be parsed for markup
  *
diff --git a/gtk/gtkfilechooser.c b/gtk/gtkfilechooser.c
index a0d4e1d9bb..d088f0b375 100644
--- a/gtk/gtkfilechooser.c
+++ b/gtk/gtkfilechooser.c
@@ -887,9 +887,9 @@ gtk_file_chooser_get_filenames (GtkFileChooser *chooser)
  * The user will be shown the full contents of the current folder,
  * plus user interface elements for navigating to other folders.
  *
- * In general, you should not use this function.  See the <link
- * linkend="gtkfilechooserdialog-setting-up">section on setting up a file
- * chooser dialog</link> for the rationale behind this.
+ * In general, you should not use this function.  See the
+ * [section on setting up a file chooser dialog][gtkfilechooserdialog-setting-up]
+ * for the rationale behind this.
  *
  * Return value: Not useful.
  *
@@ -1232,9 +1232,9 @@ gtk_file_chooser_get_uris (GtkFileChooser *chooser)
  * The user will be shown the full contents of the current folder,
  * plus user interface elements for navigating to other folders.
  *
- * In general, you should not use this function.  See the <link
- * linkend="gtkfilechooserdialog-setting-up">section on setting up a file
- * chooser dialog</link> for the rationale behind this.
+ * In general, you should not use this function.  See the
+ * [section on setting up a file chooser dialog][gtkfilechooserdialog-setting-up]
+ * for the rationale behind this.
  *
  * Return value: %TRUE if the folder could be changed successfully, %FALSE
  * otherwise.
diff --git a/gtk/gtkfilechooserdialog.c b/gtk/gtkfilechooserdialog.c
index 790a423b9c..8731f41769 100644
--- a/gtk/gtkfilechooserdialog.c
+++ b/gtk/gtkfilechooserdialog.c
@@ -171,7 +171,7 @@
  * appropriate.
  *
  * To summarize, make sure you use a
- * <link linkend="gtkfilechooserdialog-responses">stock response code</link>
+ * [stock response code][gtkfilechooserdialog-responses]
  * when you use #GtkFileChooserDialog to ensure proper operation.
  */
 
diff --git a/gtk/gtkfilechooserwidget.c b/gtk/gtkfilechooserwidget.c
index fdef11552a..ec5cb3a548 100644
--- a/gtk/gtkfilechooserwidget.c
+++ b/gtk/gtkfilechooserwidget.c
@@ -7167,7 +7167,7 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class)
    * name.
    *
    * The ::location-popup signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted when the user asks for it.
    *
    * This is used to make the file chooser show a "Location"
@@ -7198,7 +7198,7 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class)
    * @widget: the object which received the signal.
    *
    * The ::location-popup-on-paste signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted when the user asks for it.
    *
    * This is used to make the file chooser show a "Location"
@@ -7220,7 +7220,7 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class)
    * @widget: the object which received the signal.
    *
    * The ::location-toggle-popup signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted when the user asks for it.
    *
    * This is used to toggle the visibility of a "Location"
@@ -7243,7 +7243,7 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class)
    * @widget: the object which received the signal.
    *
    * The ::up-folder signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted when the user asks for it.
    *
    * This is used to make the file chooser go to the parent of
@@ -7265,7 +7265,7 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class)
    * @widget: the object which received the signal.
    *
    * The ::down-folder signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted when the user asks for it.
    *
    * This is used to make the file chooser go to a child of the
@@ -7291,7 +7291,7 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class)
    * @widget: the object which received the signal.
    *
    * The ::home-folder signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted when the user asks for it.
    *
    * This is used to make the file chooser show the user's home
@@ -7313,7 +7313,7 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class)
    * @widget: the object which received the signal.
    *
    * The ::desktop-folder signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted when the user asks for it.
    *
    * This is used to make the file chooser show the user's Desktop
@@ -7336,7 +7336,7 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class)
    * @bookmark_index: the number of the bookmark to switch to
    *
    * The ::quick-bookmark signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted when the user asks for it.
    *
    * This is used to make the file chooser switch to the bookmark
@@ -7364,7 +7364,7 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class)
    * @widget: the object which received the signal.
    *
    * The ::show-hidden signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted when the user asks for it.
    *
    * This is used to make the file chooser display hidden files.
@@ -7385,7 +7385,7 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class)
    * @widget: the object which received the signal.
    *
    * The ::search-shortcut signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted when the user asks for it.
    *
    * This is used to make the file chooser show the search entry.
@@ -7406,7 +7406,7 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class)
    * @widget: the object which received the signal.
    *
    * The ::recent-shortcut signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted when the user asks for it.
    *
    * This is used to make the file chooser show the Recent location.
diff --git a/gtk/gtkflowbox.c b/gtk/gtkflowbox.c
index 2ba42dcaa3..22ad2cf1a1 100644
--- a/gtk/gtkflowbox.c
+++ b/gtk/gtkflowbox.c
@@ -592,7 +592,7 @@ gtk_flow_box_child_class_init (GtkFlowBoxChildClass *class)
    * double-clicking, or by using the Space or Enter key.
    *
    * While this signal is used as a
-   * <link linkend="keybinding-signals">keybinding signal</link>,
+   * [keybinding signal][keybinding-signals],
    * it can be used by applications for their own purposes.
    */
   child_signals[CHILD_ACTIVATE] =
@@ -3792,7 +3792,7 @@ gtk_flow_box_class_init (GtkFlowBoxClass *class)
    * @box: the #GtkFlowBox on which the signal is emitted
    *
    * The ::activate-cursor-child signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted when the user activates the @box.
    */
   signals[ACTIVATE_CURSOR_CHILD] = g_signal_new ("activate-cursor-child",
@@ -3808,7 +3808,7 @@ gtk_flow_box_class_init (GtkFlowBoxClass *class)
    * @box: the #GtkFlowBox on which the signal is emitted
    *
    * The ::toggle-cursor-child signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which toggles the selection of the child that has the focus.
    *
    * The default binding for this signal is Ctrl-Space.
@@ -3828,7 +3828,7 @@ gtk_flow_box_class_init (GtkFlowBoxClass *class)
    * @count: the number of @step units to move
    *
    * The ::move-cursor signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted when the user initiates a cursor movement.
    * If the cursor is not visible in @text_view, this signal causes
    * the viewport to be moved instead.
@@ -3858,7 +3858,7 @@ gtk_flow_box_class_init (GtkFlowBoxClass *class)
    * @box: the #GtkFlowBox on which the signal is emitted
    *
    * The ::select-all signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted to select all children of the box, if
    * the selection mode permits it.
    *
@@ -3877,7 +3877,7 @@ gtk_flow_box_class_init (GtkFlowBoxClass *class)
    * @box: the #GtkFlowBox on which the signal is emitted
    *
    * The ::unselect-all signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted to unselect all children of the box, if
    * the selection mode permits it.
    *
diff --git a/gtk/gtkgrid.c b/gtk/gtkgrid.c
index 2d536d8383..15754e7a62 100644
--- a/gtk/gtkgrid.c
+++ b/gtk/gtkgrid.c
@@ -38,7 +38,7 @@
  * rows and columns. It is a very similar to #GtkTable and #GtkBox,
  * but it consistently uses #GtkWidget's #GtkWidget:margin and #GtkWidget:expand
  * properties instead of custom child properties, and it fully supports
- * <link linkend="geometry-management">height-for-width geometry management</link>.
+ * [height-for-width geometry management][geometry-management].
  *
  * Children are added using gtk_grid_attach(). They can span multiple
  * rows or columns. It is also possible to add a child next to an
diff --git a/gtk/gtkiconview.c b/gtk/gtkiconview.c
index d52d8fdb78..f4184f3d6e 100644
--- a/gtk/gtkiconview.c
+++ b/gtk/gtkiconview.c
@@ -724,7 +724,7 @@ gtk_icon_view_class_init (GtkIconViewClass *klass)
    * GtkIconView::select-all:
    * @iconview: the object on which the signal is emitted
    *
-   * A <link linkend="keybinding-signals">keybinding signal</link>
+   * A [keybinding signal][keybinding-signals]
    * which gets emitted when the user selects all items.
    *
    * Applications should not connect to it, but may emit it with
@@ -746,7 +746,7 @@ gtk_icon_view_class_init (GtkIconViewClass *klass)
    * GtkIconView::unselect-all:
    * @iconview: the object on which the signal is emitted
    *
-   * A <link linkend="keybinding-signals">keybinding signal</link>
+   * A [keybinding signal][keybinding-signals]
    * which gets emitted when the user unselects all items.
    *
    * Applications should not connect to it, but may emit it with
@@ -768,7 +768,7 @@ gtk_icon_view_class_init (GtkIconViewClass *klass)
    * GtkIconView::select-cursor-item:
    * @iconview: the object on which the signal is emitted
    *
-   * A <link linkend="keybinding-signals">keybinding signal</link>
+   * A [keybinding signal][keybinding-signals]
    * which gets emitted when the user selects the item that is currently
    * focused.
    *
@@ -791,7 +791,7 @@ gtk_icon_view_class_init (GtkIconViewClass *klass)
    * GtkIconView::toggle-cursor-item:
    * @iconview: the object on which the signal is emitted
    *
-   * A <link linkend="keybinding-signals">keybinding signal</link>
+   * A [keybinding signal][keybinding-signals]
    * which gets emitted when the user toggles whether the currently
    * focused item is selected or not. The exact effect of this 
    * depend on the selection mode.
@@ -815,7 +815,7 @@ gtk_icon_view_class_init (GtkIconViewClass *klass)
    * GtkIconView::activate-cursor-item:
    * @iconview: the object on which the signal is emitted
    *
-   * A <link linkend="keybinding-signals">keybinding signal</link>
+   * A [keybinding signal][keybinding-signals]
    * which gets emitted when the user activates the currently 
    * focused item. 
    *
@@ -841,7 +841,7 @@ gtk_icon_view_class_init (GtkIconViewClass *klass)
    * @count: the number of @step units to move
    *
    * The ::move-cursor signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted when the user initiates a cursor movement.
    *
    * Applications should not connect to it, but may emit it with
diff --git a/gtk/gtkimcontext.c b/gtk/gtkimcontext.c
index ba60a81387..4b17b2aea6 100644
--- a/gtk/gtkimcontext.c
+++ b/gtk/gtkimcontext.c
@@ -92,7 +92,7 @@
  *
  * After a new loadable input method module has been installed on the system,
  * the configuration file `gtk.immodules` needs to be
- * regenerated by <link linkend="gtk-query-immodules-3.0">gtk-query-immodules-3.0</link>,
+ * regenerated by [gtk-query-immodules-3.0][gtk-query-immodules-3.0],
  * in order for the new input method to become available to GTK+ applications.
  */
 
diff --git a/gtk/gtkinfobar.c b/gtk/gtkinfobar.c
index e48048a1c3..902b5420ef 100644
--- a/gtk/gtkinfobar.c
+++ b/gtk/gtkinfobar.c
@@ -481,7 +481,7 @@ gtk_info_bar_class_init (GtkInfoBarClass *klass)
    * GtkInfoBar::close:
    *
    * The ::close signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted when the user uses a keybinding to dismiss
    * the info bar.
    *
diff --git a/gtk/gtklabel.c b/gtk/gtklabel.c
index d0b5908666..7cb976a2e9 100644
--- a/gtk/gtklabel.c
+++ b/gtk/gtklabel.c
@@ -134,8 +134,8 @@
  * # Markup (styled text)
  *
  * To make it easy to format text in a label (changing colors,
- * fonts, etc.), label text can be provided in a simple <link
- * linkend="PangoMarkupFormat">markup format</link>.
+ * fonts, etc.), label text can be provided in a simple
+ * [markup format][PangoMarkupFormat].
  *
  * Here's how to create a label with a small font:
  * |[<!-- language="C" -->
@@ -143,8 +143,7 @@
  *   gtk_label_set_markup (GTK_LABEL (label), "<small>Small text</small>");
  * ]|
  *
- * (See <link
- * linkend="PangoMarkupFormat">complete documentation</link> of available
+ * (See [complete documentation][PangoMarkupFormat] of available
  * tags in the Pango manual.)
  *
  * The markup passed to gtk_label_set_markup() must be valid; for example,
@@ -194,7 +193,7 @@
  *
  * Note that the interpretation of #GtkLabel:width-chars and
  * #GtkLabel:max-width-chars has changed a bit with the introduction of
- * <link linkend="geometry-management">width-for-height geometry management.</link>
+ * [width-for-height geometry management.][geometry-management]
  *
  * # Links
  *
@@ -583,7 +582,7 @@ gtk_label_class_init (GtkLabelClass *class)
    * @extend_selection: %TRUE if the move should extend the selection
    *
    * The ::move-cursor signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted when the user initiates a cursor movement.
    * If the cursor is not visible in @entry, this signal causes
    * the viewport to be moved instead.
@@ -617,7 +616,7 @@ gtk_label_class_init (GtkLabelClass *class)
    * @label: the object which received the signal
    *
    * The ::copy-clipboard signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted to copy the selection to the clipboard.
    *
    * The default binding for this signal is Ctrl-c.
@@ -657,7 +656,7 @@ gtk_label_class_init (GtkLabelClass *class)
      * GtkLabel::activate-current-link:
      * @label: The label on which the signal was emitted
      *
-     * A <link linkend="keybinding-signals">keybinding signal</link>
+     * A [keybinding signal][keybinding-signals]
      * which gets emitted when the user activates a link in the label.
      *
      * Applications may also emit the signal with g_signal_emit_by_name()
@@ -845,7 +844,7 @@ gtk_label_class_init (GtkLabelClass *class)
    * The desired width of the label, in characters. If this property is set to
    * -1, the width will be calculated automatically.
    *
-   * See the section on <link linkend="label-text-layout">text layout</link>
+   * See the section on [text layout][label-text-layout]
    * for details of how #GtkLabel:width-chars and #GtkLabel:max-width-chars
    * determine the width of ellipsized and wrapped labels.
    *
@@ -906,7 +905,7 @@ gtk_label_class_init (GtkLabelClass *class)
    * The desired maximum width of the label, in characters. If this property 
    * is set to -1, the width will be calculated automatically.
    *
-   * See the section on <link linkend="label-text-layout">text layout</link>
+   * See the section on [text layout][label-text-layout]
    * for details of how #GtkLabel:width-chars and #GtkLabel:max-width-chars
    * determine the width of ellipsized and wrapped labels.
    *
@@ -2593,10 +2592,10 @@ gtk_label_set_markup_internal (GtkLabel    *label,
 /**
  * gtk_label_set_markup:
  * @label: a #GtkLabel
- * @str: a markup string (see <link linkend="PangoMarkupFormat">Pango markup format</link>)
- * 
- * Parses @str which is marked up with the <link
- * linkend="PangoMarkupFormat">Pango text markup language</link>, setting the
+ * @str: a markup string (see [Pango markup format][PangoMarkupFormat])
+ *
+ * Parses @str which is marked up with the
+ * [Pango text markup language][PangoMarkupFormat], setting the
  * label's text and attribute list based on the parse results. If the @str is
  * external data, you may need to escape it with g_markup_escape_text() or
  * g_markup_printf_escaped()<!-- -->:
@@ -2629,10 +2628,10 @@ gtk_label_set_markup (GtkLabel    *label,
  * gtk_label_set_markup_with_mnemonic:
  * @label: a #GtkLabel
  * @str: a markup string (see
- *     <link linkend="PangoMarkupFormat">Pango markup format</link>)
+ *     [Pango markup format][PangoMarkupFormat])
  *
  * Parses @str which is marked up with the
- * <link linkend="PangoMarkupFormat">Pango text markup language</link>,
+ * [Pango text markup language][PangoMarkupFormat],
  * setting the label's text and attribute list based on the parse results.
  * If characters in @str are preceded by an underscore, they are underlined
  * indicating that they represent a keyboard accelerator called a mnemonic.
@@ -5574,9 +5573,9 @@ gtk_label_get_layout_offsets (GtkLabel *label,
  * @label: a #GtkLabel
  * @setting: %TRUE if the label's text should be parsed for markup.
  *
- * Sets whether the text of the label contains markup in <link
- * linkend="PangoMarkupFormat">Pango's text markup
- * language</link>. See gtk_label_set_markup().
+ * Sets whether the text of the label contains markup in
+ * [Pango's text markup language][PangoMarkupFormat].
+ * See gtk_label_set_markup().
  **/
 void
 gtk_label_set_use_markup (GtkLabel *label,
@@ -5597,8 +5596,8 @@ gtk_label_set_use_markup (GtkLabel *label,
  * @label: a #GtkLabel
  *
  * Returns whether the label's text is interpreted as marked up with
- * the <link linkend="PangoMarkupFormat">Pango text markup
- * language</link>. See gtk_label_set_use_markup ().
+ * the [Pango text markup language][PangoMarkupFormat].
+ * See gtk_label_set_use_markup ().
  *
  * Return value: %TRUE if the label's text will be parsed for markup.
  **/
diff --git a/gtk/gtkliststore.c b/gtk/gtkliststore.c
index b1292d3cbe..0217a53b17 100644
--- a/gtk/gtkliststore.c
+++ b/gtk/gtkliststore.c
@@ -40,7 +40,7 @@
  * can use all of the methods available there.  It also implements the
  * #GtkTreeSortable interface so it can be sorted by the view.
  * Finally, it also implements the tree
- * <link linkend="gtk3-GtkTreeView-drag-and-drop">drag and drop</link>
+ * [drag and drop][gtk3-GtkTreeView-drag-and-drop]
  * interfaces.
  *
  * The #GtkListStore can accept most GObject types as a column type, though
diff --git a/gtk/gtkmessagedialog.c b/gtk/gtkmessagedialog.c
index 68ba03bb4a..0362cf7b7e 100644
--- a/gtk/gtkmessagedialog.c
+++ b/gtk/gtkmessagedialog.c
@@ -593,7 +593,7 @@ gtk_message_dialog_new (GtkWindow     *parent,
  *
  * Creates a new message dialog, which is a simple dialog with an icon
  * indicating the dialog type (error, warning, etc.) and some text which
- * is marked up with the <link linkend="PangoMarkupFormat">Pango text markup language</link>.
+ * is marked up with the [Pango text markup language][PangoMarkupFormat].
  * When the user clicks a button a “response” signal is emitted with
  * response IDs from #GtkResponseType. See #GtkDialog for more details.
  *
@@ -712,11 +712,10 @@ gtk_message_dialog_get_image (GtkMessageDialog *dialog)
 /**
  * gtk_message_dialog_set_markup:
  * @message_dialog: a #GtkMessageDialog
- * @str: markup string (see <link linkend="PangoMarkupFormat">Pango markup format</link>)
+ * @str: markup string (see [Pango markup format][PangoMarkupFormat])
  * 
  * Sets the text of the message dialog to be @str, which is marked
- * up with the <link linkend="PangoMarkupFormat">Pango text markup
- * language</link>.
+ * up with the [Pango text markup language][PangoMarkupFormat].
  *
  * Since: 2.4
  **/
@@ -784,12 +783,12 @@ gtk_message_dialog_format_secondary_text (GtkMessageDialog *message_dialog,
  * gtk_message_dialog_format_secondary_markup:
  * @message_dialog: a #GtkMessageDialog
  * @message_format: printf()-style markup string (see
-     <link linkend="PangoMarkupFormat">Pango markup format</link>), or %NULL
+     [Pango markup format][PangoMarkupFormat]), or %NULL
  * @...: arguments for @message_format
  *
  * Sets the secondary text of the message dialog to be @message_format (with
  * printf()-style), which is marked up with the
- * <link linkend="PangoMarkupFormat">Pango text markup language</link>.
+ * [Pango text markup language][PangoMarkupFormat].
  *
  * Due to an oversight, this function does not escape special XML characters
  * like gtk_message_dialog_new_with_markup() does. Thus, if the arguments
diff --git a/gtk/gtkpagesetupunixdialog.c b/gtk/gtkpagesetupunixdialog.c
index 3b320ced32..3b757ea22f 100644
--- a/gtk/gtkpagesetupunixdialog.c
+++ b/gtk/gtkpagesetupunixdialog.c
@@ -53,8 +53,8 @@
  * #GtkPageSetupUnixDialog implements a page setup dialog for platforms
  * which don't provide a native page setup dialog, like Unix. It can
  * be used very much like any other GTK+ dialog, at the cost of
- * the portability offered by the <link
- * linkend="gtk3-High-level-Printing-API">high-level printing API</link>
+ * the portability offered by the
+ * [high-level printing API][gtk3-High-level-Printing-API]
  *
  * Printing support was added in GTK+ 2.10.
  */
diff --git a/gtk/gtkpaned.c b/gtk/gtkpaned.c
index c9f1ea6105..e97de29f2b 100644
--- a/gtk/gtkpaned.c
+++ b/gtk/gtkpaned.c
@@ -443,7 +443,7 @@ gtk_paned_class_init (GtkPanedClass *class)
    * @reversed: whether cycling backward or forward
    *
    * The ::cycle-child-focus signal is a 
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted to cycle the focus between the children of the paned.
    *
    * The default binding is f6.
@@ -465,7 +465,7 @@ gtk_paned_class_init (GtkPanedClass *class)
    * @widget: the object that received the signal
    *
    * The ::toggle-handle-focus is a 
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted to accept the current position of the handle and then 
    * move focus to the next widget in the focus chain.
    *
@@ -488,7 +488,7 @@ gtk_paned_class_init (GtkPanedClass *class)
    * @scroll_type: a #GtkScrollType
    *
    * The ::move-handle signal is a 
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted to move the handle when the user is using key bindings 
    * to move it.
    *
@@ -510,7 +510,7 @@ gtk_paned_class_init (GtkPanedClass *class)
    * @reversed: whether cycling backward or forward
    *
    * The ::cycle-handle-focus signal is a 
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted to cycle whether the paned should grab focus to allow
    * the user to change position of the handle by using key bindings.
    *
@@ -533,7 +533,7 @@ gtk_paned_class_init (GtkPanedClass *class)
    * @widget: the object that received the signal
    *
    * The ::accept-position signal is a 
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted to accept the current position of the handle when 
    * moving it using key bindings.
    *
@@ -555,7 +555,7 @@ gtk_paned_class_init (GtkPanedClass *class)
    * @widget: the object that received the signal
    *
    * The ::cancel-position signal is a 
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted to cancel moving the position of the handle using key 
    * bindings. The position of the handle will be reset to the value prior to 
    * moving it.
diff --git a/gtk/gtkpapersize.c b/gtk/gtkpapersize.c
index d0e8bfb690..6fca06eabf 100644
--- a/gtk/gtkpapersize.c
+++ b/gtk/gtkpapersize.c
@@ -52,7 +52,7 @@
  *
  * The #GtkPaperSize object stores not only the dimensions (width
  * and height) of a paper size and its name, it also provides
- * default <link linkend="print-margins">print margins</link>.
+ * default [print margins][print-margins].
  *
  * Printing support has been added in GTK+ 2.10.
  */
diff --git a/gtk/gtkprintunixdialog.c b/gtk/gtkprintunixdialog.c
index 735d1f16b8..d142eb6b06 100644
--- a/gtk/gtkprintunixdialog.c
+++ b/gtk/gtkprintunixdialog.c
@@ -68,7 +68,7 @@
  * which don't provide a native print dialog, like Unix. It can
  * be used very much like any other GTK+ dialog, at the cost of
  * the portability offered by the
- * <link linkend="gtk3-High-level-Printing-API">high-level printing API</link>
+ * [high-level printing API][gtk3-High-level-Printing-API]
  *
  * In order to print something with #GtkPrintUnixDialog, you need
  * to use gtk_print_unix_dialog_get_selected_printer() to obtain
diff --git a/gtk/gtkscale.c b/gtk/gtkscale.c
index 079f712eb6..cf1a39bd6f 100644
--- a/gtk/gtkscale.c
+++ b/gtk/gtkscale.c
@@ -1580,7 +1580,7 @@ gtk_scale_clear_marks (GtkScale *scale)
  *   and %GTK_POS_LEFT are drawn above the scale, anything else below.
  *   For a vertical scale, #GTK_POS_LEFT and %GTK_POS_TOP are drawn to
  *   the left of the scale, anything else to the right.
- * @markup: (allow-none): Text to be shown at the mark, using <link linkend="PangoMarkupFormat">Pango markup</link>, or %NULL
+ * @markup: (allow-none): Text to be shown at the mark, using [Pango markup][PangoMarkupFormat], or %NULL
  *
  *
  * Adds a mark at @value.
diff --git a/gtk/gtkscalebutton.c b/gtk/gtkscalebutton.c
index d1bd058bf4..fd76382a64 100644
--- a/gtk/gtkscalebutton.c
+++ b/gtk/gtkscalebutton.c
@@ -269,7 +269,7 @@ gtk_scale_button_class_init (GtkScaleButtonClass *klass)
    * @button: the object which received the signal
    *
    * The ::popup signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted to popup the scale widget.
    *
    * The default bindings for this signal are Space, Enter and Return.
@@ -290,7 +290,7 @@ gtk_scale_button_class_init (GtkScaleButtonClass *klass)
    * @button: the object which received the signal
    *
    * The ::popdown signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted to popdown the scale widget.
    *
    * The default binding for this signal is Escape.
diff --git a/gtk/gtkscrolledwindow.c b/gtk/gtkscrolledwindow.c
index 6566eb9c66..9ebb1d9211 100644
--- a/gtk/gtkscrolledwindow.c
+++ b/gtk/gtkscrolledwindow.c
@@ -498,7 +498,7 @@ gtk_scrolled_window_class_init (GtkScrolledWindowClass *class)
    *   horizontally or not
    *
    * The ::scroll-child signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted when a keybinding that scrolls is pressed.
    * The horizontal or vertical adjustment is updated which triggers a
    * signal that the scrolled windows child may listen to and scroll itself.
@@ -520,8 +520,8 @@ gtk_scrolled_window_class_init (GtkScrolledWindowClass *class)
    * @direction_type: either %GTK_DIR_TAB_FORWARD or
    *   %GTK_DIR_TAB_BACKWARD
    *
-   * The ::move-focus-out signal is a <link
-   * linkend="keybinding-signals">keybinding signal</link> which gets
+   * The ::move-focus-out signal is a
+   * [keybinding signal][keybinding-signals] which gets
    * emitted when focus is moved away from the scrolled window by a
    * keybinding.  The #GtkWidget::move-focus signal is emitted with
    * @direction_type on this scrolled windows toplevel parent in the
diff --git a/gtk/gtksettings.c b/gtk/gtksettings.c
index 25f39499dc..8d93f76ee3 100644
--- a/gtk/gtksettings.c
+++ b/gtk/gtksettings.c
@@ -722,7 +722,7 @@ gtk_settings_class_init (GtkSettingsClass *class)
    * ...
    * ]|
    * Color names must be acceptable as identifiers in the
-   * <link linkend="gtk3-Resource-Files">gtkrc</link> syntax, and
+   * [gtkrc][gtk3-Resource-Files] syntax, and
    * color specifications must be in the format accepted by
    * gdk_color_parse().
    *
diff --git a/gtk/gtkstatusicon.c b/gtk/gtkstatusicon.c
index 2cc342b559..791d11db1b 100644
--- a/gtk/gtkstatusicon.c
+++ b/gtk/gtkstatusicon.c
@@ -393,8 +393,8 @@ gtk_status_icon_class_init (GtkStatusIconClass *class)
    * GtkStatusIcon:tooltip-markup:
    *
    * Sets the text of tooltip to be the given string, which is marked up
-   * with the <link linkend="PangoMarkupFormat">Pango text markup 
-   * language</link>. Also see gtk_tooltip_set_markup().
+   * with the [Pango text markup language][PangoMarkupFormat].
+   * Also see gtk_tooltip_set_markup().
    *
    * This is a convenience property which will take care of getting the
    * tooltip shown if the given string is not %NULL.
@@ -2530,7 +2530,7 @@ gtk_status_icon_get_tooltip_text (GtkStatusIcon *status_icon)
  * @markup: (allow-none): the contents of the tooltip for @status_icon, or %NULL
  *
  * Sets @markup as the contents of the tooltip, which is marked up with
- *  the <link linkend="PangoMarkupFormat">Pango text markup language</link>.
+ *  the [Pango text markup language][PangoMarkupFormat].
  *
  * This function will take care of setting #GtkStatusIcon:has-tooltip to %TRUE
  * and of the default handler for the #GtkStatusIcon::query-tooltip signal.
diff --git a/gtk/gtktextbuffer.c b/gtk/gtktextbuffer.c
index 558dd7f61b..8919e11e61 100644
--- a/gtk/gtktextbuffer.c
+++ b/gtk/gtktextbuffer.c
@@ -47,8 +47,9 @@
  * @Title: GtkTextBuffer
  * @See_also: #GtkTextView, #GtkTextIter, #GtkTextMark
  *
- * You may wish to begin by reading the <link linkend="TextWidget">text widget
- * conceptual overview</link> which gives an overview of all the objects and data
+ * You may wish to begin by reading the
+ * [text widget conceptual overview][TextWidget]
+ * which gives an overview of all the objects and data
  * types related to the text widget and how they work together.
  */
 
diff --git a/gtk/gtktextiter.c b/gtk/gtktextiter.c
index cfdf53ccb1..b3a7f2a0d8 100644
--- a/gtk/gtktextiter.c
+++ b/gtk/gtktextiter.c
@@ -38,8 +38,9 @@
  * @Short_description: Text buffer iterator
  * @Title: GtkTextIter
  *
- * You may wish to begin by reading the <link linkend="TextWidget">text widget
- * conceptual overview</link> which gives an overview of all the objects and data
+ * You may wish to begin by reading the
+ * [text widget conceptual overview][TextWidget]
+ * which gives an overview of all the objects and data
  * types related to the text widget and how they work together.
  */
 
diff --git a/gtk/gtktextmark.c b/gtk/gtktextmark.c
index 7c72004e2c..919b5c9c5b 100644
--- a/gtk/gtktextmark.c
+++ b/gtk/gtktextmark.c
@@ -59,8 +59,9 @@
  * @Short_description: A position in the buffer preserved across buffer modifications
  * @Title: GtkTextMark
  *
- * You may wish to begin by reading the <link linkend="TextWidget">text widget
- * conceptual overview</link> which gives an overview of all the objects and data
+ * You may wish to begin by reading the
+ * [text widget conceptual overview][TextWidget]
+ * which gives an overview of all the objects and data
  * types related to the text widget and how they work together.
  *
  * A #GtkTextMark is like a bookmark in a text buffer; it preserves a position in
diff --git a/gtk/gtktexttag.c b/gtk/gtktexttag.c
index b566c2c579..9718a9c762 100644
--- a/gtk/gtktexttag.c
+++ b/gtk/gtktexttag.c
@@ -52,8 +52,9 @@
  * @Title: GtkTextTag
  * @Short_description: A tag that can be applied to text in a GtkTextBuffer
  *
- * You may wish to begin by reading the <link linkend="TextWidget">text widget
- * conceptual overview</link> which gives an overview of all the objects and
+ * You may wish to begin by reading the
+ * [text widget conceptual overview][TextWidget]
+ * which gives an overview of all the objects and
  * data types related to the text widget and how they work together.
  *
  * Tags should be in the #GtkTextTagTable for a given #GtkTextBuffer
diff --git a/gtk/gtktexttagtable.c b/gtk/gtktexttagtable.c
index 29245c1cbb..fdf9cfebb3 100644
--- a/gtk/gtktexttagtable.c
+++ b/gtk/gtktexttagtable.c
@@ -40,8 +40,9 @@
  * @Short_description: Collection of tags that can be used together
  * @Title: GtkTextTagTable
  *
- * You may wish to begin by reading the <link linkend="TextWidget">text widget
- * conceptual overview</link> which gives an overview of all the objects and
+ * You may wish to begin by reading the
+ * [text widget conceptual overview][TextWidget]
+ * which gives an overview of all the objects and
  * data types related to the text widget and how they work together.
  *
  * # GtkTextTagTables as GtkBuildable
diff --git a/gtk/gtktextview.c b/gtk/gtktextview.c
index 1614fe26b1..daa7a3b31a 100644
--- a/gtk/gtktextview.c
+++ b/gtk/gtktextview.c
@@ -64,8 +64,9 @@
  * @Title: GtkTextView
  * @See_also: #GtkTextBuffer, #GtkTextIter
  *
- * You may wish to begin by reading the <link linkend="TextWidget">text widget
- * conceptual overview</link> which gives an overview of all the objects and data
+ * You may wish to begin by reading the
+ * [text widget conceptual overview][TextWidget]
+ * which gives an overview of all the objects and data
  * types related to the text widget and how they work together.
  */
 
@@ -927,7 +928,7 @@ gtk_text_view_class_init (GtkTextViewClass *klass)
    * @extend_selection: %TRUE if the move should extend the selection
    *  
    * The ::move-cursor signal is a 
-   * <link linkend="keybinding-signals">keybinding signal</link> 
+   * [keybinding signal][keybinding-signals] 
    * which gets emitted when the user initiates a cursor movement. 
    * If the cursor is not visible in @text_view, this signal causes
    * the viewport to be moved instead.
@@ -965,7 +966,7 @@ gtk_text_view_class_init (GtkTextViewClass *klass)
    * @count: the number of @step units to move
    *
    * The ::move-viewport signal is a 
-   * <link linkend="keybinding-signals">keybinding signal</link> 
+   * [keybinding signal][keybinding-signals] 
    * which can be bound to key combinations to allow the user
    * to move the viewport, i.e. change what part of the text view
    * is visible in a containing scrolled window.
@@ -988,7 +989,7 @@ gtk_text_view_class_init (GtkTextViewClass *klass)
    * @text_view: the object which received the signal
    *
    * The ::set-anchor signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted when the user initiates setting the "anchor" 
    * mark. The "anchor" mark gets placed at the same position as the
    * "insert" mark.
@@ -1010,7 +1011,7 @@ gtk_text_view_class_init (GtkTextViewClass *klass)
    * @string: the string to insert
    *
    * The ::insert-at-cursor signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted when the user initiates the insertion of a 
    * fixed string at the cursor.
    *
@@ -1033,7 +1034,7 @@ gtk_text_view_class_init (GtkTextViewClass *klass)
    * @count: the number of @type units to delete
    *
    * The ::delete-from-cursor signal is a 
-   * <link linkend="keybinding-signals">keybinding signal</link> 
+   * [keybinding signal][keybinding-signals] 
    * which gets emitted when the user initiates a text deletion.
    *
    * If the @type is %GTK_DELETE_CHARS, GTK+ deletes the selection
@@ -1061,7 +1062,7 @@ gtk_text_view_class_init (GtkTextViewClass *klass)
    * @text_view: the object which received the signal
    *
    * The ::backspace signal is a 
-   * <link linkend="keybinding-signals">keybinding signal</link> 
+   * [keybinding signal][keybinding-signals] 
    * which gets emitted when the user asks for it.
    * 
    * The default bindings for this signal are
@@ -1081,7 +1082,7 @@ gtk_text_view_class_init (GtkTextViewClass *klass)
    * @text_view: the object which received the signal
    *
    * The ::cut-clipboard signal is a 
-   * <link linkend="keybinding-signals">keybinding signal</link> 
+   * [keybinding signal][keybinding-signals] 
    * which gets emitted to cut the selection to the clipboard.
    * 
    * The default bindings for this signal are
@@ -1101,7 +1102,7 @@ gtk_text_view_class_init (GtkTextViewClass *klass)
    * @text_view: the object which received the signal
    *
    * The ::copy-clipboard signal is a 
-   * <link linkend="keybinding-signals">keybinding signal</link> 
+   * [keybinding signal][keybinding-signals] 
    * which gets emitted to copy the selection to the clipboard.
    * 
    * The default bindings for this signal are
@@ -1121,7 +1122,7 @@ gtk_text_view_class_init (GtkTextViewClass *klass)
    * @text_view: the object which received the signal
    *
    * The ::paste-clipboard signal is a 
-   * <link linkend="keybinding-signals">keybinding signal</link> 
+   * [keybinding signal][keybinding-signals] 
    * which gets emitted to paste the contents of the clipboard 
    * into the text view.
    * 
@@ -1142,7 +1143,7 @@ gtk_text_view_class_init (GtkTextViewClass *klass)
    * @text_view: the object which received the signal
    *
    * The ::toggle-overwrite signal is a 
-   * <link linkend="keybinding-signals">keybinding signal</link> 
+   * [keybinding signal][keybinding-signals] 
    * which gets emitted to toggle the overwrite mode of the text view.
    * 
    * The default bindings for this signal is Insert.
@@ -1192,7 +1193,7 @@ gtk_text_view_class_init (GtkTextViewClass *klass)
    * @select: %TRUE to select, %FALSE to unselect
    *
    * The ::select-all signal is a 
-   * <link linkend="keybinding-signals">keybinding signal</link> 
+   * [keybinding signal][keybinding-signals] 
    * which gets emitted to select or unselect the complete
    * contents of the text view.
    *
@@ -1213,7 +1214,7 @@ gtk_text_view_class_init (GtkTextViewClass *klass)
    * @text_view: the object which received the signal
    *
    * The ::toggle-cursor-visible signal is a 
-   * <link linkend="keybinding-signals">keybinding signal</link> 
+   * [keybinding signal][keybinding-signals] 
    * which gets emitted to toggle the visibility of the cursor.
    *
    * The default binding for this signal is F7.
diff --git a/gtk/gtktooltip.c b/gtk/gtktooltip.c
index d0a544804b..47ae1cb3d2 100644
--- a/gtk/gtktooltip.c
+++ b/gtk/gtktooltip.c
@@ -277,11 +277,10 @@ gtk_tooltip_dispose (GObject *object)
 /**
  * gtk_tooltip_set_markup:
  * @tooltip: a #GtkTooltip
- * @markup: (allow-none): a markup string (see <link linkend="PangoMarkupFormat">Pango markup format</link>) or %NULL
+ * @markup: (allow-none): a markup string (see [Pango markup format][PangoMarkupFormat]) or %NULL
  *
  * Sets the text of the tooltip to be @markup, which is marked up
- * with the <link
- * linkend="PangoMarkupFormat">Pango text markup language</link>.
+ * with the [Pango text markup language][PangoMarkupFormat].
  * If @markup is %NULL, the label will be hidden.
  *
  * Since: 2.12
diff --git a/gtk/gtktreemodel.c b/gtk/gtktreemodel.c
index d066f82f51..1312d645e9 100644
--- a/gtk/gtktreemodel.c
+++ b/gtk/gtktreemodel.c
@@ -32,7 +32,7 @@
  * @Title: GtkTreeModel
  * @Short_description: The tree interface used by GtkTreeView
  * @See_also: #GtkTreeView, #GtkTreeStore, #GtkListStore,
- *     <link linkend="gtk3-GtkTreeView-drag-and-drop">GtkTreeView drag-and-drop</link>
+ *     [GtkTreeView drag-and-drop][gtk3-GtkTreeView-drag-and-drop]
  *     #GtkTreeSortable
  *
  * The #GtkTreeModel interface defines a generic tree interface for
diff --git a/gtk/gtktreeselection.c b/gtk/gtktreeselection.c
index b1df51550a..0b14d0e599 100644
--- a/gtk/gtktreeselection.c
+++ b/gtk/gtktreeselection.c
@@ -33,7 +33,7 @@
  * @See_also: #GtkTreeView, #GtkTreeViewColumn, #GtkTreeModel,
  *   #GtkTreeSortable, #GtkTreeModelSort, #GtkListStore, #GtkTreeStore,
  *   #GtkCellRenderer, #GtkCellEditable, #GtkCellRendererPixbuf,
- *   #GtkCellRendererText, #GtkCellRendererToggle, <link linkend="gtk3-GtkTreeView-drag-and-drop">GtkTreeView drag-and-drop</link>
+ *   #GtkCellRendererText, #GtkCellRendererToggle, [GtkTreeView drag-and-drop][gtk3-GtkTreeView-drag-and-drop]
  *
  * The #GtkTreeSelection object is a helper object to manage the selection
  * for a #GtkTreeView widget.  The #GtkTreeSelection object is
diff --git a/gtk/gtktreestore.c b/gtk/gtktreestore.c
index 6b346ca80b..8bfdd8ee62 100644
--- a/gtk/gtktreestore.c
+++ b/gtk/gtktreestore.c
@@ -38,7 +38,7 @@
  * can use all of the methods available there.  It also implements the
  * #GtkTreeSortable interface so it can be sorted by the view.  Finally,
  * it also implements the tree
- * <link linkend="gtk3-GtkTreeView-drag-and-drop">drag and drop</link>
+ * [drag and drop][gtk3-GtkTreeView-drag-and-drop]
  * interfaces.
  *
  * # GtkTreeStore as GtkBuildable
diff --git a/gtk/gtktreeview.c b/gtk/gtktreeview.c
index ad65749cd8..201df03c40 100644
--- a/gtk/gtktreeview.c
+++ b/gtk/gtktreeview.c
@@ -63,15 +63,16 @@
  * @Short_description: A widget for displaying both trees and lists
  * @Title: GtkTreeView
  * @See_also: #GtkTreeViewColumn, #GtkTreeSelection, #GtkTreeModel,
- *   <link linkend="gtk3-GtkTreeView-drag-and-drop">GtkTreeView drag-and-drop</link>,
+ *   [GtkTreeView drag-and-drop][gtk3-GtkTreeView-drag-and-drop],
  *   #GtkTreeSortable, #GtkTreeModelSort, #GtkListStore, #GtkTreeStore,
  *   #GtkCellRenderer, #GtkCellEditable, #GtkCellRendererPixbuf,
  *   #GtkCellRendererText, #GtkCellRendererToggle
  *
  * Widget that displays any object that implements the #GtkTreeModel interface.
  *
- * Please refer to the <link linkend="TreeWidget">tree widget conceptual
- * overview</link> for an overview of all the objects and data types related
+ * Please refer to the
+ * [tree widget conceptual overview][TreeWidget]
+ * for an overview of all the objects and data types related
  * to the tree widget and how they work together.
  *
  * Several different coordinate systems are exposed in the GtkTreeView API.
@@ -1285,9 +1286,10 @@ gtk_tree_view_class_init (GtkTreeViewClass *class)
    * the "activate-on-single-click" property set to %TRUE. It is also
    * emitted when a non-editable row is selected and one of the keys:
    * Space, Shift+Space, Return or Enter is pressed.
-   * 
-   * For selection handling refer to the <link linkend="TreeWidget">tree 
-   * widget conceptual overview</link> as well as #GtkTreeSelection.
+   *
+   * For selection handling refer to the
+   * [tree widget conceptual overview][TreeWidget]
+   * as well as #GtkTreeSelection.
    */
   tree_view_signals[ROW_ACTIVATED] =
     g_signal_new (I_("row-activated"),
diff --git a/gtk/gtktreeviewcolumn.c b/gtk/gtktreeviewcolumn.c
index b08045f5b6..26225f2fbd 100644
--- a/gtk/gtktreeviewcolumn.c
+++ b/gtk/gtktreeviewcolumn.c
@@ -45,13 +45,13 @@
  * @See_also: #GtkTreeView, #GtkTreeSelection, #GtkTreeModel, #GtkTreeSortable,
  *   #GtkTreeModelSort, #GtkListStore, #GtkTreeStore, #GtkCellRenderer, #GtkCellEditable,
  *   #GtkCellRendererPixbuf, #GtkCellRendererText, #GtkCellRendererToggle,
- *   <link linkend="gtk3-GtkTreeView-drag-and-drop">GtkTreeView drag-and-drop</link>
+ *   [GtkTreeView drag-and-drop][gtk3-GtkTreeView-drag-and-drop]
  *
  * The GtkTreeViewColumn object represents a visible column in a #GtkTreeView widget.
  * It allows to set properties of the column header, and functions as a holding pen for
  * the cell renderers which determine how the data in the column is displayed.
  *
- * Please refer to the <link linkend="TreeWidget">tree widget conceptual overview</link>
+ * Please refer to the [tree widget conceptual overview][TreeWidget]
  * for an overview of all the objects and data types related to the tree widget and how
  * they work together.
  */
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 3a1ad0b5e5..a599b13af0 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -132,8 +132,8 @@
  * requested. For this reason, #GtkWidget caches a  small number of results
  * to avoid re-querying for the same sizes in one allocation cycle.
  *
- * See <link linkend="container-geometry-management">GtkContainer's
- * geometry management section</link>
+ * See
+ * [GtkContainer's geometry management section][container-geometry-management]
  * to learn more about how height-for-width allocations are performed
  * by container widgets.
  *
@@ -244,7 +244,7 @@
  * #GtkWidget introduces “style
  * properties” - these are basically object properties that are stored
  * not on the object, but in the style object associated to the widget. Style
- * properties are set in <link linkend="gtk3-Resource-Files">resource files</link>.
+ * properties are set in [resource files][gtk3-Resource-Files].
  * This mechanism is used for configuring such things as the location of the
  * scrollbar arrows through the theme, giving theme authors more control over the
  * look of applications without the need to write a theme engine in C.
@@ -1296,7 +1296,7 @@ G_GNUC_END_IGNORE_DEPRECATIONS
    * GtkWidget:tooltip-markup:
    *
    * Sets the text of tooltip to be the given string, which is marked up
-   * with the <link linkend="PangoMarkupFormat">Pango text markup language</link>.
+   * with the [Pango text markup language][PangoMarkupFormat].
    * Also see gtk_tooltip_set_markup().
    *
    * This is a convenience property which will take care of getting the
@@ -1959,7 +1959,7 @@ G_GNUC_END_IGNORE_DEPRECATIONS
    * @child_property: the #GParamSpec of the changed child property
    *
    * The ::child-notify signal is emitted for each
-   * <link linkend="child-properties">child property</link>  that has
+   * [child property][child-properties]  that has
    * changed on an object. The signal's detail holds the property name.
    */
   widget_signals[CHILD_NOTIFY] =
@@ -4062,7 +4062,7 @@ gtk_widget_freeze_child_notify (GtkWidget *widget)
  *                  class of @widget<!-- -->'s parent
  *
  * Emits a #GtkWidget::child-notify signal for the
- * <link linkend="child-properties">child property</link> @child_property
+ * [child property][child-properties] @child_property
  * on @widget.
  *
  * This is the analogue of g_object_notify() for child properties.
@@ -14748,7 +14748,7 @@ gtk_widget_get_tooltip_text (GtkWidget *widget)
  * @markup: (allow-none): the contents of the tooltip for @widget, or %NULL
  *
  * Sets @markup as the contents of the tooltip, which is marked up with
- *  the <link linkend="PangoMarkupFormat">Pango text markup language</link>.
+ *  the [Pango text markup language][PangoMarkupFormat].
  *
  * This function will take care of setting #GtkWidget:has-tooltip to %TRUE
  * and of the default handler for the #GtkWidget::query-tooltip signal.
diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index 0cb630542b..960784e220 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -1170,7 +1170,7 @@ gtk_window_class_init (GtkWindowClass *klass)
    * @window: the window which received the signal
    *
    * The ::activate-focus signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted when the user activates the currently
    * focused widget of @window.
    */
@@ -1189,7 +1189,7 @@ gtk_window_class_init (GtkWindowClass *klass)
    * @window: the window which received the signal
    *
    * The ::activate-default signal is a
-   * <link linkend="keybinding-signals">keybinding signal</link>
+   * [keybinding signal][keybinding-signals]
    * which gets emitted when the user activates the default widget
    * of @window.
    */
@@ -1832,8 +1832,8 @@ gtk_window_buildable_custom_finished (GtkBuildable  *buildable,
  * you might use #GTK_WINDOW_POPUP. #GTK_WINDOW_POPUP is not for
  * dialogs, though in some other toolkits dialogs are called “popups”.
  * In GTK+, #GTK_WINDOW_POPUP means a pop-up menu or pop-up tooltip.
- * On X11, popup windows are not controlled by the <link
- * linkend="gtk-X11-arch">window manager</link>.
+ * On X11, popup windows are not controlled by the
+ * [window manager][gtk-X11-arch].
  *
  * If you simply want an undecorated window (no window borders), use
  * gtk_window_set_decorated(), don't use #GTK_WINDOW_POPUP.
@@ -1901,8 +1901,8 @@ gtk_window_set_title_internal (GtkWindow   *window,
  * 
  * Sets the title of the #GtkWindow. The title of a window will be
  * displayed in its title bar; on the X Window System, the title bar
- * is rendered by the <link linkend="gtk-X11-arch">window
- * manager</link>, so exactly how the title appears to users may vary
+ * is rendered by the [window manager][gtk-X11-arch],
+ * so exactly how the title appears to users may vary
  * according to a user's exact configuration. The title should help a
  * user distinguish this window from other windows they may have
  * open. A good title might include the application name and current
@@ -1981,7 +1981,7 @@ gtk_window_set_wmclass (GtkWindow *window,
  * This function is only useful on X11, not with other GTK+ targets.
  * 
  * In combination with the window title, the window role allows a
- * <link linkend="gtk-X11-arch">window manager</link> to identify "the
+ * [window manager][gtk-X11-arch] to identify "the
  * same" window when an application is restarted. So for example you
  * might set the “toolbox” role on your app's toolbox window, so that
  * when the user restarts their session, the window manager can put
@@ -2567,7 +2567,7 @@ gtk_window_activate_default (GtkWindow *window)
  * with other windows in the same application. To keep modal dialogs
  * on top of main application windows, use
  * gtk_window_set_transient_for() to make the dialog transient for the
- * parent; most <link linkend="gtk-X11-arch">window managers</link>
+ * parent; most [window managers][gtk-X11-arch]
  * will then disallow lowering the dialog below the parent.
  * 
  * 
@@ -2786,8 +2786,8 @@ gtk_window_unset_transient_for  (GtkWindow *window)
  * @parent: (allow-none): parent window, or %NULL
  *
  * Dialog windows should be set transient for the main application
- * window they were spawned from. This allows <link
- * linkend="gtk-X11-arch">window managers</link> to e.g. keep the
+ * window they were spawned from. This allows
+ * [window managers][gtk-X11-arch] to e.g. keep the
  * dialog on top of the main window, or center the dialog over the
  * main window. gtk_dialog_new_with_buttons() and other convenience
  * functions in GTK+ will sometimes call
@@ -3753,8 +3753,8 @@ _gtk_window_titlebar_shows_app_menu (GtkWindow *window)
  * @setting: %TRUE to decorate the window
  *
  * By default, windows are decorated with a title bar, resize
- * controls, etc.  Some <link linkend="gtk-X11-arch">window
- * managers</link> allow GTK+ to disable these decorations, creating a
+ * controls, etc.  Some [window managers][gtk-X11-arch]
+ * allow GTK+ to disable these decorations, creating a
  * borderless window. If you set the decorated property to %FALSE
  * using this function, GTK+ will do its best to convince the window
  * manager not to decorate the window. Depending on the system, this
@@ -3828,7 +3828,7 @@ gtk_window_get_decorated (GtkWindow *window)
  * @setting: %TRUE to decorate the window as deletable
  *
  * By default, windows have a close button in the window frame. Some 
- * <link linkend="gtk-X11-arch">window managers</link> allow GTK+ to 
+ * [window managers][gtk-X11-arch] allow GTK+ to 
  * disable this button. If you set the deletable property to %FALSE
  * using this function, GTK+ will do its best to convince the window
  * manager not to show a close button. Depending on the system, this
@@ -4843,8 +4843,9 @@ gtk_window_resize_to_geometry (GtkWindow *window,
  * @height: (out) (allow-none): return location for height, or %NULL
  *
  * Obtains the current size of @window. If @window is not onscreen,
- * it returns the size GTK+ will suggest to the <link
- * linkend="gtk-X11-arch">window manager</link> for the initial window
+ * it returns the size GTK+ will suggest to the
+ * [window manager][gtk-X11-arch]
+ * for the initial window
  * size (but this is not reliably the same as the size the window
  * manager will actually select). The size obtained by
  * gtk_window_get_size() is the last size received in a
@@ -4929,7 +4930,7 @@ gtk_window_get_size (GtkWindow *window,
  * @x: X coordinate to move window to
  * @y: Y coordinate to move window to
  *
- * Asks the <link linkend="gtk-X11-arch">window manager</link> to move
+ * Asks the [window manager][gtk-X11-arch] to move
  * @window to the given position.  Window managers are free to ignore
  * this; most window managers ignore requests for initial window
  * positions (instead using a user-defined placement algorithm) and
@@ -10020,8 +10021,8 @@ gtk_window_present_with_time (GtkWindow *window,
  *
  * Asks to iconify (i.e. minimize) the specified @window. Note that
  * you shouldn't assume the window is definitely iconified afterward,
- * because other entities (e.g. the user or <link
- * linkend="gtk-X11-arch">window manager</link>) could deiconify it
+ * because other entities (e.g. the user or
+ * [window manager][gtk-X11-arch]) could deiconify it
  * again, or there may not be a window manager in which case
  * iconification isn't possible, etc. But normally the window will end
  * up iconified. Just don't write code that crashes if not.
@@ -10060,8 +10061,8 @@ gtk_window_iconify (GtkWindow *window)
  *
  * Asks to deiconify (i.e. unminimize) the specified @window. Note
  * that you shouldn't assume the window is definitely deiconified
- * afterward, because other entities (e.g. the user or <link
- * linkend="gtk-X11-arch">window manager</link>) could iconify it
+ * afterward, because other entities (e.g. the user or
+ * [window manager][gtk-X11-arch])) could iconify it
  * again before your code which assumes deiconification gets to run.
  *
  * You can track iconification via the “window-state-event” signal
@@ -10093,8 +10094,8 @@ gtk_window_deiconify (GtkWindow *window)
  *
  * Asks to stick @window, which means that it will appear on all user
  * desktops. Note that you shouldn't assume the window is definitely
- * stuck afterward, because other entities (e.g. the user or <link
- * linkend="gtk-X11-arch">window manager</link>) could unstick it
+ * stuck afterward, because other entities (e.g. the user or
+ * [window manager][gtk-X11-arch] could unstick it
  * again, and some window managers do not support sticking
  * windows. But normally the window will end up stuck. Just don't
  * write code that crashes if not.
@@ -10132,8 +10133,8 @@ gtk_window_stick (GtkWindow *window)
  * Asks to unstick @window, which means that it will appear on only
  * one of the user's desktops. Note that you shouldn't assume the
  * window is definitely unstuck afterward, because other entities
- * (e.g. the user or <link linkend="gtk-X11-arch">window
- * manager</link>) could stick it again. But normally the window will
+ * (e.g. the user or [window manager][gtk-X11-arch]) could
+ * stick it again. But normally the window will
  * end up stuck. Just don't write code that crashes if not.
  *
  * You can track stickiness via the “window-state-event” signal
@@ -10166,8 +10167,8 @@ gtk_window_unstick (GtkWindow *window)
  *
  * Asks to maximize @window, so that it becomes full-screen. Note that
  * you shouldn't assume the window is definitely maximized afterward,
- * because other entities (e.g. the user or <link
- * linkend="gtk-X11-arch">window manager</link>) could unmaximize it
+ * because other entities (e.g. the user or
+ * [window manager][gtk-X11-arch]) could unmaximize it
  * again, and not all window managers support maximization. But
  * normally the window will end up maximized. Just don't write code
  * that crashes if not.
@@ -10207,8 +10208,8 @@ gtk_window_maximize (GtkWindow *window)
  *
  * Asks to unmaximize @window. Note that you shouldn't assume the
  * window is definitely unmaximized afterward, because other entities
- * (e.g. the user or <link linkend="gtk-X11-arch">window
- * manager</link>) could maximize it again, and not all window
+ * (e.g. the user or [window manager][gtk-X11-arch])
+ * could maximize it again, and not all window
  * managers honor requests to unmaximize. But normally the window will
  * end up unmaximized. Just don't write code that crashes if not.
  *
@@ -10242,8 +10243,8 @@ gtk_window_unmaximize (GtkWindow *window)
  *
  * Asks to place @window in the fullscreen state. Note that you
  * shouldn't assume the window is definitely full screen afterward,
- * because other entities (e.g. the user or <link
- * linkend="gtk-X11-arch">window manager</link>) could unfullscreen it
+ * because other entities (e.g. the user or
+ * [window manager][gtk-X11-arch]) could unfullscreen it
  * again, and not all window managers honor requests to fullscreen
  * windows. But normally the window will end up fullscreen. Just
  * don't write code that crashes if not.
@@ -10279,8 +10280,8 @@ gtk_window_fullscreen (GtkWindow *window)
  *
  * Asks to toggle off the fullscreen state for @window. Note that you
  * shouldn't assume the window is definitely not full screen
- * afterward, because other entities (e.g. the user or <link
- * linkend="gtk-X11-arch">window manager</link>) could fullscreen it
+ * afterward, because other entities (e.g. the user or
+ * [window manager][gtk-X11-arch]) could fullscreen it
  * again, and not all window managers honor requests to unfullscreen
  * windows. But normally the window will end up restored to its normal
  * state. Just don't write code that crashes if not.
@@ -10317,8 +10318,8 @@ gtk_window_unfullscreen (GtkWindow *window)
  *
  * Asks to keep @window above, so that it stays on top. Note that
  * you shouldn't assume the window is definitely above afterward,
- * because other entities (e.g. the user or <link
- * linkend="gtk-X11-arch">window manager</link>) could not keep it above,
+ * because other entities (e.g. the user or
+ * [window manager][gtk-X11-arch]) could not keep it above,
  * and not all window managers support keeping windows above. But
  * normally the window will end kept above. Just don't write code
  * that crashes if not.
@@ -10368,8 +10369,8 @@ gtk_window_set_keep_above (GtkWindow *window,
  *
  * Asks to keep @window below, so that it stays in bottom. Note that
  * you shouldn't assume the window is definitely below afterward,
- * because other entities (e.g. the user or <link
- * linkend="gtk-X11-arch">window manager</link>) could not keep it below,
+ * because other entities (e.g. the user or
+ * [window manager][gtk-X11-arch]) could not keep it below,
  * and not all window managers support putting windows below. But
  * normally the window will be kept below. Just don't write code
  * that crashes if not.
@@ -10523,8 +10524,8 @@ gtk_window_get_gravity (GtkWindow *window)
  *
  * Starts resizing a window. This function is used if an application
  * has window resizing controls. When GDK can support it, the resize
- * will be done using the standard mechanism for the <link
- * linkend="gtk-X11-arch">window manager</link> or windowing
+ * will be done using the standard mechanism for the
+ * [window manager][gtk-X11-arch] or windowing
  * system. Otherwise, GDK will try to emulate window resizing,
  * potentially not all that well, depending on the windowing system.
  */
@@ -10561,8 +10562,8 @@ gtk_window_begin_resize_drag  (GtkWindow     *window,
  *
  * Starts moving a window. This function is used if an application has
  * window movement grips. When GDK can support it, the window movement
- * will be done using the standard mechanism for the <link
- * linkend="gtk-X11-arch">window manager</link> or windowing
+ * will be done using the standard mechanism for the
+ * [window manager][gtk-X11-arch] or windowing
  * system. Otherwise, GDK will try to emulate window movement,
  * potentially not all that well, depending on the windowing system.
  */