docs: don't use <para id="">

gdk/gdkkeys.c

@@ -57,7 +57,8 @@
  * When it makes sense, key values can be converted to and from
  * Unicode characters with gdk_keyval_to_unicode() and gdk_unicode_to_keyval().
  *
- * <para id="key-group-explanation">
+ * # Groups # {#key-group-explanation}
+ *
  * One #GdkKeymap object exists for each user display. gdk_keymap_get_default()
  * returns the #GdkKeymap for the default display; to obtain keymaps for other
  * displays, use gdk_keymap_get_for_display(). A keymap
@@ -78,7 +79,6 @@
  * group 0, a key might have two English characters, and in group 1 it might have
  * two Hebrew characters. The Hebrew characters will be printed on the key next to
  * the English characters.
- * </para>
  *
  * In order to use a keymap to interpret a key event, it's necessary to first
  * convert the keyboard state into an effective group and level. This is done via a

gdk/gdkwindow.c

@@ -60,20 +60,20 @@
  * and so on; a #GtkWindow may contain many #GdkWindows. For example,
  * each #GtkButton has a #GdkWindow associated with it.
  *
- * ## Composited Windows
+ * # Composited Windows # {#COMPOSITED-WINDOWS}
  *
- * <para id="COMPOSITED-WINDOWS">Normally, the windowing system takes care of rendering the contents
+ * Normally, the windowing system takes care of rendering the contents
  * of a child window onto its parent window. This mechanism can be
  * intercepted by calling gdk_window_set_composited() on the child
  * window. For a “composited” window it is the
  * responsibility of the application to render the window contents at
- * the right spot.</para>
+ * the right spot.
  *
- * ## Offscreen Windows
+ * # Offscreen Windows # {#OFFSCREEN-WINDOWS}
  *
- * <para id="OFFSCREEN-WINDOWS">Offscreen windows are more general than composited windows, since
+ * Offscreen windows are more general than composited windows, since
  * they allow not only to modify the rendering of the child window onto
- * its parent, but also to apply coordinate transformations.</para>
+ * its parent, but also to apply coordinate transformations.
  *
  * To integrate an offscreen window into a window hierarchy, one has
  * to call gdk_offscreen_window_set_embedder() and handle a number of

gtk/gtkcssprovider.c

@@ -91,13 +91,13 @@
  * }
  * ]|
  *
- * ## Selectors
+ * # Selectors # {#gtkcssprovider-selectors}
  *
- * <para id="gtkcssprovider-selectors">Selectors work very similar to the way they do in CSS, with widget class
+ * Selectors work very similar to the way they do in CSS, with widget class
  * names taking the role of element names, and widget names taking the role
  * of IDs. When used in a selector, widget names must be prefixed with a
  * '&num;' character. The '*' character represents the so-called universal
- * selector, which matches any widget.</para>
+ * selector, which matches any widget.
  *
  * To express more complicated situations, selectors can be combined in
  * various ways:

gtk/gtkfilechooser.c

@@ -91,8 +91,8 @@
  * gtk_file_chooser_set_preview_widget_active() with a boolean
  * flag that indicates whether your callback could successfully
  * generate a preview.
- * 
- * <para id="gtkfilechooser-preview">An example for using a  preview widget:</para>
+ *
+ * ## An example for using a preview widget ## {#gtkfilechooser-preview}
  * |[<!-- language="C" -->
  * {
  *   GtkImage *preview;

gtk/gtkpagesetup.c

@@ -36,13 +36,12 @@
  * these affect the actual layout of the page, and thus need to be set
  * long before user prints.
  *
- * <para id="print-margins">
+ * ## Margins ## {#print-margins}
  * The margins specified in this object are the "print margins", i.e. the
  * parts of the page that the printer cannot print on. These are different
  * from the layout margins that a word processor uses; they are typically
  * used to determine the minimal size for the layout
  * margins.
- * </para>
  *
  * To obtain a #GtkPageSetup use gtk_page_setup_new() to get the defaults,
  * or use gtk_print_run_page_setup_dialog() to show the page setup dialog

gtk/gtkstylecontext.c

@@ -75,7 +75,7 @@
  * #GtkSettings:gtk-theme-name setting or a hierarchy change in the rendered
  * widget.
  *
- * ## Transition animations
+ * # Transition animations
  *
  * #GtkStyleContext has built-in support for state change transitions.
  * Note that these animations respect the #GtkSettings:gtk-enable-animations
@@ -97,6 +97,7 @@
  * enumeration works well:
  *
  * An example for Using an enumeration to identify animatable regions:
+ *
  * |[<!-- language="C" -->
  * enum {
  *   REGION_ENTRY,
@@ -171,11 +172,11 @@
  * special value, in this case, the whole widget area will be updated
  * by the animation.
  *
- * ## Style classes and regions
+ * # Style classes and regions # {#gtkstylecontext-classes}
  *
- * <para id="gtkstylecontext-classes">Widgets can add style classes to their context, which can be used
+ * Widgets can add style classes to their context, which can be used
  * to associate different styles by class (see <xref linkend="gtkcssprovider-selectors"/>).
- * Theme engines can also use style classes to vary their rendering.</para>
+ * Theme engines can also use style classes to vary their rendering.
  *
  * Widgets can also add regions with flags to their context.
  * The regions used by GTK+ widgets are:

gtk/gtkwidget.c

@@ -77,17 +77,18 @@
  * GtkWidget is the base class all widgets in GTK+ derive from. It manages the
  * widget lifecycle, states and style.
  *
- * ## Height-for-width Geometry Management
+ * # Height-for-width Geometry Management # {#geometry-management}
  *
- * <para id="geometry-management">GTK+ uses a height-for-width (and width-for-height) geometry management
+ * GTK+ uses a height-for-width (and width-for-height) geometry management
  * system. Height-for-width means that a widget can change how much
  * vertical space it needs, depending on the amount of horizontal space
  * that it is given (and similar for width-for-height). The most common
  * example is a label that reflows to fill up the available width, wraps
- * to fewer lines, and therefore needs less height.</para>
+ * to fewer lines, and therefore needs less height.
  *
  * Height-for-width geometry management is implemented in GTK+ by way
  * of five virtual methods:
+ *
  * - #GtkWidgetClass.get_request_mode()
  * - #GtkWidgetClass.get_preferred_width()
  * - #GtkWidgetClass.get_preferred_height()
@@ -152,6 +153,7 @@
  * Here are some examples of how a %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH widget
  * generally deals with width-for-height requests, for #GtkWidgetClass.get_preferred_height()
  * it will do:
+ *
  * |[<!-- language="C" -->
  * static void
  * foo_widget_get_preferred_height (GtkWidget *widget, gint *min_height, gint *nat_height)
@@ -197,6 +199,7 @@
  * compute width. Or when deciding how to use an allocation, the widget
  * may need to know its natural size. In these cases, the widget should
  * be careful to call its virtual methods directly, like this:
+ *
  * |[<!-- language="C" -->
  * GTK_WIDGET_GET_CLASS(widget)-&gt;get_preferred_width (widget),
  *                                  &min, &natural);