add forgotten file

ngl: Small clipping improvements
Handle the fully contained cases for clip nodes. No need to intersect the clip in this case.
2021-03-14 12:07:50 -04:00 · 2021-03-14 00:59:43 -05:00 · 2021-03-14 00:09:36 -05:00 · 2021-03-13 23:38:54 -05:00 · 2021-03-13 18:59:11 -05:00 · 2021-03-13 18:21:45 -05:00
578 changed files with 63524 additions and 59434 deletions
@@ -26,7 +26,7 @@ variables:
  MESON_TEST_TIMEOUT_MULTIPLIER: 3
  FEDORA_IMAGE: "registry.gitlab.gnome.org/gnome/gtk/fedora:v28"
  FLATPAK_IMAGE: "registry.gitlab.gnome.org/gnome/gnome-runtime-images/gnome:master"
-  DOCS_IMAGE: "registry.gitlab.gnome.org/gnome/gtk/fedora-docs:v25"
+  DOCS_IMAGE: "registry.gitlab.gnome.org/gnome/gtk/fedora-docs:v26"

 .only-default:
  only:
@@ -290,11 +290,13 @@ reference:
    EXTRA_MESON_FLAGS: "--buildtype=release"
  script:
    - meson ${COMMON_MESON_FLAGS} ${EXTRA_MESON_FLAGS} -Dgtk_doc=true _build
-    - ninja -C _build gdk4-doc gsk4-doc gtk4-doc
+    - meson compile -C _build
    - mkdir -p _reference/
-    - mv _build/docs/reference/gdk/html/ _reference/gdk/
-    - mv _build/docs/reference/gsk/html/ _reference/gsk/
-    - mv _build/docs/reference/gtk/html/ _reference/gtk/
+    - mv _build/docs/reference/gdk/gdk4/ _reference/gdk4/
+    - mv _build/docs/reference/gdk/gdk4-x11/ _reference/gdk4-x11/
+    - mv _build/docs/reference/gdk/gdk4-wayland/ _reference/gdk4-wayland/
+    - mv _build/docs/reference/gsk/gsk4/ _reference/gsk4/
+    - mv _build/docs/reference/gtk/gtk4/ _reference/gtk4/
  artifacts:
    paths:
      - _reference
@@ -17,8 +17,8 @@ branch, as well as their available versions.
 ### Checklist for Updating a CI image

 - [ ] Update the `${image}.Dockerfile` file with the dependencies
- - [ ] Run `./run-docker.sh build --base ${image} --base-version ${number}`
- - [ ] Run `./run-docker.sh push --base ${image} --base-version ${number}`
+ - [ ] Run `./run-docker.sh build --base ${image} --version ${number}`
+ - [ ] Run `./run-docker.sh push --base ${image} --version ${number}`
   once the Docker image is built; you may need to log in by using
   `docker login` or `podman login`
 - [ ] Update the `image` keys in the `.gitlab-ci.yml` file with the new
@@ -30,8 +30,8 @@ branch, as well as their available versions.
 - [ ] Write a new `${image}.Dockerfile` with the instructions to set up
   a build environment
 - [ ] Add the `pip3 install meson` incantation
- - [ ] Run `./run-docker.sh build --base ${image} --base-version ${number}`
- - [ ] Run `./run-docker.sh push --base ${image} --base-version ${number}`
+ - [ ] Run `./run-docker.sh build --base ${image} --version ${number}`
+ - [ ] Run `./run-docker.sh push --base ${image} --version ${number}`
 - [ ] Add the new job to `.gitlab-ci.yml` referencing the image
 - [ ] Open a merge request with your changes and let it run

@@ -1,6 +1,11 @@
-FROM registry.gitlab.gnome.org/gnome/gtk/fedora-base:v25
+FROM registry.gitlab.gnome.org/gnome/gtk/fedora-base:v28

-RUN dnf -y install pandoc
+RUN dnf -y install \
+        python3-jinja2 \
+        python3-markdown \
+        python3-pygments \
+        python3-toml \
+        python3-typogrify

 ARG HOST_USER_ID=5555
 ENV HOST_USER_ID ${HOST_USER_ID}
@@ -32,7 +32,7 @@ while (($# > 0)); do
                list) list=1;;
                help) print_help=1;;
                --base|-b) read_arg base "$@" || shift;;
-                --base-version) read_arg base_version "$@" || shift;;
+                --version|-v) read_arg base_version "$@" || shift;;
                --no-login) no_login=1;;
                *) echo -e "\e[1;31mERROR\e[0m: Unknown option '$1'"; exit 1;;
        esac
@@ -32,9 +32,9 @@ Discussion forum
  - https://discourse.gnome.org/c/platform/core/

 Nightly documentation can be found at
-  - Gtk: https://gnome.pages.gitlab.gnome.org/gtk/gtk/
-  - Gdk: https://gnome.pages.gitlab.gnome.org/gtk/gdk/
-  - Gsk: https://gnome.pages.gitlab.gnome.org/gtk/gsk/
+  - Gtk: https://gnome.pages.gitlab.gnome.org/gtk/gtk4/
+  - Gdk: https://gnome.pages.gitlab.gnome.org/gtk/gdk4/
+  - Gsk: https://gnome.pages.gitlab.gnome.org/gtk/gsk4/

 Building and installing
 -----------------------
@@ -35,15 +35,15 @@
    "modules" : [
        {
            "name" : "wayland",
-            "buildsystem" : "autotools",
+            "buildsystem" : "meson",
            "builddir" : true,
            "config-opts" : [
-                "--disable-documentation"
+                "-Ddocumentation=false"
            ],
            "sources" : [
                {
                    "type" : "git",
-                    "url" : "https://github.com/wayland-project/wayland.git"
+                    "url" : "https://gitlab.freedesktop.org/wayland/wayland.git"
                }
            ]
        },
@@ -63,6 +63,36 @@
                }
            ]
        },
+        {
+            "name" : "libsass",
+            "buildsystem" : "meson",
+            "builddir" : true,
+            "config-opts" : [
+                "--libdir=/app/lib"
+            ],
+            "sources" : [
+                {
+                    "type" : "git",
+                    "url" : "https://github.com/lazka/libsass.git",
+                    "branch" : "meson"
+                }
+            ]
+        },
+        {
+            "name" : "sassc",
+            "buildsystem" : "meson",
+            "builddir" : true,
+            "config-opts" : [
+                "--libdir=/app/lib"
+            ],
+            "sources" : [
+                {
+                    "type" : "git",
+                    "url" : "https://github.com/lazka/sassc.git",
+                    "branch" : "meson"
+                }
+            ]
+        },
        {
            "name" : "gtk",
            "buildsystem" : "meson",
@@ -70,7 +100,6 @@
            "config-opts" : [
                "--libdir=/app/lib",
                "-Denable_vulkan=no",
-                "-Dsassc=disabled",
                "-Dbuildtype=debugoptimized",
                "-Dprofile=devel"
            ],
@@ -35,15 +35,15 @@
    "modules" : [
        {
            "name" : "wayland",
-            "buildsystem" : "autotools",
+            "buildsystem" : "meson",
            "builddir" : true,
            "config-opts" : [
-                "--disable-documentation"
+                "-Ddocumentation=false"
            ],
            "sources" : [
                {
                    "type" : "git",
-                    "url" : "https://github.com/wayland-project/wayland.git"
+                    "url" : "https://gitlab.freedesktop.org/wayland/wayland.git"
                }
            ]
        },
@@ -63,6 +63,36 @@
                }
            ]
        },
+        {
+            "name" : "libsass",
+            "buildsystem" : "meson",
+            "builddir" : true,
+            "config-opts" : [
+                "--libdir=/app/lib"
+            ],
+            "sources" : [
+                {
+                    "type" : "git",
+                    "url" : "https://github.com/lazka/libsass.git",
+                    "branch" : "meson"
+                }
+            ]
+        },
+        {
+            "name" : "sassc",
+            "buildsystem" : "meson",
+            "builddir" : true,
+            "config-opts" : [
+                "--libdir=/app/lib"
+            ],
+            "sources" : [
+                {
+                    "type" : "git",
+                    "url" : "https://github.com/lazka/sassc.git",
+                    "branch" : "meson"
+                }
+            ]
+        },
        {
            "name" : "gtk",
            "buildsystem" : "meson",
@@ -70,7 +100,6 @@
            "config-opts" : [
                "--libdir=/app/lib",
                "-Denable_vulkan=no",
-                "-Dsassc=disabled",
                "-Dbuildtype=debugoptimized",
                "-Dprofile=devel"
            ],
@@ -35,15 +35,15 @@
    "modules" : [
        {
            "name" : "wayland",
-            "buildsystem" : "autotools",
+            "buildsystem" : "meson",
            "builddir" : true,
            "config-opts" : [
-                "--disable-documentation"
+                "-Ddocumentation=false"
            ],
            "sources" : [
                {
                    "type" : "git",
-                    "url" : "https://github.com/wayland-project/wayland.git"
+                    "url" : "https://gitlab.freedesktop.org/wayland/wayland.git"
                }
            ]
        },
@@ -63,6 +63,36 @@
                }
            ]
        },
+        {
+            "name" : "libsass",
+            "buildsystem" : "meson",
+            "builddir" : true,
+            "config-opts" : [
+                "--libdir=/app/lib"
+            ],
+            "sources" : [
+                {
+                    "type" : "git",
+                    "url" : "https://github.com/lazka/libsass.git",
+                    "branch" : "meson"
+                }
+            ]
+        },
+        {
+            "name" : "sassc",
+            "buildsystem" : "meson",
+            "builddir" : true,
+            "config-opts" : [
+                "--libdir=/app/lib"
+            ],
+            "sources" : [
+                {
+                    "type" : "git",
+                    "url" : "https://github.com/lazka/sassc.git",
+                    "branch" : "meson"
+                }
+            ]
+        },
        {
            "name" : "gtk",
            "buildsystem" : "meson",
@@ -70,7 +100,6 @@
            "config-opts" : [
                "--libdir=/app/lib",
                "-Denable_vulkan=no",
-                "-Dsassc=disabled",
                "-Dbuildtype=debugoptimized",
                "-Dprofile=devel"
            ],
@@ -13,7 +13,7 @@ static GtkWidget *window = NULL;
 static GtkWidget *scrolledwindow;
 static int selected;

-#define N_WIDGET_TYPES 7
+#define N_WIDGET_TYPES 8


 static int hincrement = 5;
@@ -110,6 +110,41 @@ populate_text (gboolean highlight)
  gtk_scrolled_window_set_child (GTK_SCROLLED_WINDOW (scrolledwindow), textview);
 }

+static void
+populate_emoji_text (void)
+{
+  GtkWidget *textview;
+  GtkTextBuffer *buffer;
+  GString *s;
+
+  s = g_string_sized_new (1000 * 30 * 4);
+
+  for (int i = 0; i < 1000; i++)
+    {
+      if (i % 2)
+        g_string_append (s, "x");
+      for (int j = 0; j < 30; j++)
+        g_string_append (s, "💓x");
+      g_string_append (s, "\n");
+    }
+
+  buffer = gtk_text_buffer_new (NULL);
+  gtk_text_buffer_set_text (buffer, s->str, s->len);
+
+  g_string_free (s, TRUE);
+
+  textview = gtk_text_view_new ();
+  gtk_text_view_set_buffer (GTK_TEXT_VIEW (textview), buffer);
+
+  hincrement = 0;
+  vincrement = 5;
+
+  gtk_scrolled_window_set_policy (GTK_SCROLLED_WINDOW (scrolledwindow),
+                                  GTK_POLICY_NEVER,
+                                  GTK_POLICY_AUTOMATIC);
+  gtk_scrolled_window_set_child (GTK_SCROLLED_WINDOW (scrolledwindow), textview);
+}
+
 static void
 populate_image (void)
 {
@@ -224,21 +259,26 @@ set_widget_type (int type)
      break;

    case 3:
+      gtk_window_set_title (GTK_WINDOW (window), "Scrolling text with Emoji");
+      populate_emoji_text ();
+      break;
+
+    case 4:
      gtk_window_set_title (GTK_WINDOW (window), "Scrolling a big image");
      populate_image ();
      break;

-    case 4:
+    case 5:
      gtk_window_set_title (GTK_WINDOW (window), "Scrolling a list");
      populate_list ();
      break;

-    case 5:
+    case 6:
      gtk_window_set_title (GTK_WINDOW (window), "Scrolling a columned list");
      populate_list2 ();
      break;

-    case 6:
+    case 7:
      gtk_window_set_title (GTK_WINDOW (window), "Scrolling a grid");
      populate_grid ();
      break;
@@ -14,8 +14,10 @@ struct _IconBrowserWindow
  GtkWidget *searchbar;
  GListModel *icon_filter_model;
  GListStore *icon_store;
+  GListModel *context_model;
  GListStore *context_store;
  GtkFilter *name_filter;
+  GtkFilter *search_mode_filter;
  GtkWidget *details;
  GtkWidget *image1;
  GtkWidget *image2;
@@ -354,6 +356,28 @@ setup_scalable_image_dnd (GtkWidget *image)
  gtk_widget_add_controller (image, GTK_EVENT_CONTROLLER (source));
 }

+static void
+search_mode_toggled (GtkSearchBar      *searchbar,
+                     GParamSpec        *pspec,
+                     IconBrowserWindow *win)
+{
+  if (gtk_search_bar_get_search_mode (searchbar))
+    gtk_single_selection_set_selected (GTK_SINGLE_SELECTION (win->context_model), GTK_INVALID_LIST_POSITION);
+  else if (gtk_single_selection_get_selected (GTK_SINGLE_SELECTION (win->context_model)) == GTK_INVALID_LIST_POSITION)
+    gtk_single_selection_set_selected (GTK_SINGLE_SELECTION (win->context_model), 0);
+
+  gtk_filter_changed (win->search_mode_filter, GTK_FILTER_CHANGE_DIFFERENT);
+}
+
+static void
+selected_name_changed (GtkSingleSelection *selection,
+                       GParamSpec         *pspec,
+                       IconBrowserWindow  *win)
+{
+  if (gtk_single_selection_get_selected (selection) != GTK_INVALID_LIST_POSITION)
+    gtk_search_bar_set_search_mode (GTK_SEARCH_BAR (win->searchbar), FALSE);
+}
+
 static void
 icon_browser_window_init (IconBrowserWindow *win)
 {
@@ -380,6 +404,9 @@ icon_browser_window_init (IconBrowserWindow *win)
  win->name_filter = GTK_FILTER (gtk_custom_filter_new (filter_by_icon_name, NULL, NULL));

  gtk_multi_filter_append (GTK_MULTI_FILTER (filter), g_object_ref (win->name_filter));
+
+  g_signal_connect (win->searchbar, "notify::search-mode-enabled",  G_CALLBACK (search_mode_toggled), win);
+  g_signal_connect (win->context_model, "notify::selected",  G_CALLBACK (selected_name_changed), win);
 }

 static void
@@ -409,6 +436,7 @@ icon_browser_window_class_init (IconBrowserWindowClass *class)
  gtk_widget_class_bind_template_child (GTK_WIDGET_CLASS (class), IconBrowserWindow, searchbar);
  gtk_widget_class_bind_template_child (GTK_WIDGET_CLASS (class), IconBrowserWindow, icon_store);
  gtk_widget_class_bind_template_child (GTK_WIDGET_CLASS (class), IconBrowserWindow, icon_filter_model);
+  gtk_widget_class_bind_template_child (GTK_WIDGET_CLASS (class), IconBrowserWindow, context_model);
  gtk_widget_class_bind_template_child (GTK_WIDGET_CLASS (class), IconBrowserWindow, context_store);

  gtk_widget_class_bind_template_child (GTK_WIDGET_CLASS (class), IconBrowserWindow, details);
@@ -422,6 +450,7 @@ icon_browser_window_class_init (IconBrowserWindowClass *class)
  gtk_widget_class_bind_template_child (GTK_WIDGET_CLASS (class), IconBrowserWindow, image8);
  gtk_widget_class_bind_template_child (GTK_WIDGET_CLASS (class), IconBrowserWindow, label8);
  gtk_widget_class_bind_template_child (GTK_WIDGET_CLASS (class), IconBrowserWindow, description);
+  gtk_widget_class_bind_template_child (GTK_WIDGET_CLASS (class), IconBrowserWindow, search_mode_filter);

  gtk_widget_class_bind_template_callback (GTK_WIDGET_CLASS (class), item_activated);
  gtk_widget_class_bind_template_callback (GTK_WIDGET_CLASS (class), copy_to_clipboard);
@@ -151,19 +151,32 @@
                                  </object>
                                </child>
                                <child>
-                                  <object class="GtkStringFilter">
-                                    <property name="ignore-case">0</property>
-                                    <property name="match-mode">exact</property>
-                                    <property name="expression">
-                                      <lookup name="context" type="IbIcon"/>
-                                    </property>
-                                    <binding name="search">
-                                      <lookup name="id" type="IbContext">
-                                        <lookup name="selected-item" type="GtkSingleSelection">
-                                          context_model
-                                        </lookup>
-                                      </lookup>
-                                    </binding>
+                                  <object class="GtkAnyFilter">
+                                    <child>
+                                      <object class="GtkBoolFilter" id="search_mode_filter">
+                                        <property name="expression">
+                                          <lookup name="search-mode-enabled">
+                                             searchbar
+                                          </lookup>
+                                        </property>
+                                      </object>
+                                    </child>
+                                    <child>
+                                      <object class="GtkStringFilter">
+                                        <property name="ignore-case">0</property>
+                                        <property name="match-mode">exact</property>
+                                        <property name="expression">
+                                          <lookup name="context" type="IbIcon"/>
+                                        </property>
+                                        <binding name="search">
+                                          <lookup name="id" type="IbContext">
+                                            <lookup name="selected-item" type="GtkSingleSelection">
+                                              context_model
+                                            </lookup>
+                                          </lookup>
+                                        </binding>
+                                      </object>
+                                    </child>
                                  </object>
                                </child>
                              </object>
@@ -42,9 +42,9 @@ Creates a node like `gsk_blur_node_new()` with the given properties.

 | property | syntax           | default                | printed     |
 | -------- | ---------------- | ---------------------- | ----------- |
-| color    | `<color>{1,4}`   | black                  | non-default |
+| colors   | `<color>{1,4}`   | black                  | non-default |
 | outline  | `<rounded-rect>` | 50                     | always      |
-| width    | `<number>{1,4}`  | 1                      | non-default |
+| widths   | `<number>{1,4}`  | 1                      | non-default |

 Creates a node like `gsk_border_node_new()` with the given properties.

@@ -121,7 +121,7 @@ Creates a node like `gsk_conic_gradient_node_new()` with the given properties.
 | property | syntax           | default                | printed     |
 | -------- | ---------------- | ---------------------- | ----------- |
 | end      | `<node>`         | color { }              | always      |
-| mode     | `<number>`       | 0.5                    | non-default |
+| progress | `<number>`       | 0.5                    | non-default |
 | start    | `<node>`         | color { }              | always      |

 Creates a node like `gsk_cross_fade_node_new()` with the given properties.
@@ -246,7 +246,7 @@ Creates a node like `gsk_rounded_clip_node_new()` with the given properties.
 | property | syntax           | default                | printed     |
 | -------- | ---------------- | ---------------------- | ----------- |
 | child    | `<node>`         | color { }              | always      |
-| shadow   | `<shadow>`       | black 1 1              | always      |
+| shadows  | `<shadow>`       | black 1 1              | always      |

 Creates a node like `gsk_shadow_node_new()` with the given properties.

@@ -696,27 +696,29 @@ Public macros should not be used unless they evaluate to a constant.
 ### Symbol visibility

 Any symbol that is not explicitly annotated using a `GDK_AVAILABLE_IN_*`
-macro is considered internal, and not exported in the shared library.
+or `GDK_DEPRECATED_IN_*` macro is considered internal, and not exported
+in the shared library.

 Never export variables as public API, since this is cumbersome on some
 platforms. It is always preferable to add getters and setters instead.

 Non-exported functions that are needed in more than one source file
-should be declared in a private header file.
+should be declared in a private header file with a name that ends in
+`private.h`.

 Non-exported functions that are only needed in one source file
 should be declared static.

 ### Documentation

-All public APIs must have gtk-doc comments. For functions, these should
+All public APIs must have doc comments. For functions, these should
 be placed in the source file, directly above the function.

 ```c
  /* valid */
  /**
   * gtk_get_flow:
-   * @widget: a #GtkWidget
+   * @widget: a `GtkWidget`
   *
   * Gets the flow of a widget.
   *
@@ -736,29 +738,34 @@ be placed in the source file, directly above the function.
 Doc comments for macros, function types, class structs, etc should be
 placed next to the definitions, typically in headers.

-Section introductions should be placed in the source file they describe,
-after the license header:
+The main content of the doc comments uses markdown, which can include
+inline formatting, sections, tables, images, links. For links to
+symbols/classes/etc, we use a markdown extension syntax like this:
+
+[class@Gtk.Widget], [method@Gtk.ListView.get_factory],...
+
+Every doc comment should start with a single-sentence paragraph that
+can serve as a summary of sorts (it will often be placed next to a
+link pointing to the full documentation for the symbol/class/etc).
+The summary should not include links.
+
+Long-form documentation for classes should be included in the doc
+comment for the struct, typically at the top of the source file,
+after the license header and includes:

 ```c
-  /* valid */
  /**
-   * SECTION:gtksizerequest
-   * @Short_Description: Height-for-width geometry management
-   * @Title: GtkSizeRequest
+   * GtkSizeRequest:
+   *
+   * The GtkSizeRequest interface is GTK's height-for-width geometry
+   * geometry management system.
+   *
+   * # Geometry management
   *
-   * The GtkSizeRequest interface is GTK's height-for-width (and
-   * width-for-height) geometry management system.
   * ...
   */
 ```

-To properly document a new function, macro, function type or struct,
-it needs to be listed in the `sections.txt` file.
-
-To properly document a new class, it needs to be given its own section
-in the sections.txt, needs to be included in the `docs.xml` file, and the
-`get_type` function needs to listed in the `.types` file.
-
 For more information on the documentation style and contribution guidelines,
 please [follow the corresponding contribution guide](./reference/README.md).

@@ -6,40 +6,41 @@ The GTK documentation is divided in two major components:
   source code
 - static pages that provide an overview of specific sections of the API

-In both cases, the contents are parsed, converted into DocBook format, and
-cross-linked in order to match types, functions, signals, and properties.
-From the DocBook output, we generate HTML, which can be used to read the
-documentation both offline and online.
+In both cases, the contents are parsed as markdown and cross-linked in order
+to match types, functions, signals, and properties. Ultimatively, we generate
+HTML, which can be used to read the documentation both offline and online.

-In both cases, contributing to the GTK documentation requires modifying
-files tracked in the source control repository, and follows the same steps
-as any other code contribution as outlined in the GTK [contribution
-guide][contributing]. Please, refer to that document for any further
-question on the mechanics of contributing to GTK.
+Contributing to the GTK documentation requires modifying files tracked in the
+source control repository, and follows the same steps as any other code
+contribution as outlined in the GTK [contribution guide][contributing].
+Please, refer to that document for any further question on the mechanics
+of contributing to GTK.

-GTK uses [gtk-doc][gtkdoc] to generate its documentation. Please, visit the
-gtk-doc website to read the project's documentation.
+GTK uses [gi-docgen][gidocgen] to generate its documentation. Please, visit
+the gi-docgen website to read the project's documentation.

 [contributing]: ../../CONTRIBUTING.md
-[gtkdoc]: https://wiki.gnome.org/DocumentationProject/GtkDoc
+[gi-docgen]: https://gitlab.gnome.org/ebassi/gi-docgen

 ## Contributing to the API reference

 Whenever you need to add or modify the documentation of a type or a
-function, you will need to edit a `gtk-doc` comment stanza, typically right
+function, you will need to edit a comment stanza, typically right
 above the type or function declaration. For instance:

 ```c
 /**
 * gtk_foo_set_bar:
- * @self: a #GtkFoo
- * @bar: a #GtkBar
+ * @self: a foo widget
+ * @bar: (nullable): the bar to set
 *
- * Sets the given #GtkBar instance on a #GtkFoo widget.
+ * Sets the given `GtkBar` instance on a foo widget.
+ *
+ * Returns: `TRUE` if the bar was set
 */
-void
+gboolean
 gtk_foo_set_bar (GtkFoo *self,
-		 GtkBar *bar)
+                 GtkBar *bar)
 {
  ...
 ```
@@ -51,31 +52,14 @@ Or, for types:
 * GtkFoo:
 *
 * A foo widget instance.
- *
- * The contents of this structure are private and should never
- * be accessed directly.
 */
 struct _GtkFoo
 {
+  /*< private >*/
  GtkWidget parent_instance;
 };
 ```

-Each public function and type in the GTK API reference must be listed in the
-`sections.txt` file for the specific namespace to which it belongs: GDK,
-GSK, or GTK. For instance, if you add a function named `gtk_foo_set_bar()`,
-you will need to:
-
- 1. open `docs/reference/gtk/gtk4-sections.txt`
- 1. find the section that lists the symbols of the `GtkFoo` type
- 1. add `gtk_foo_set_bar` to the list
-
-New classes require:
-
- 1. a new section in the `sections.txt` file
- 1. the `get_type` function added to the `.types` file
- 1. an `xinclude` element in the `docs.xml` file
-
 The GTK documentation also contains a number of 'freestanding' chapters
 for which the source is in .md files in docs/reference/gtk.

@@ -90,49 +74,61 @@ unrelated reasons.

 ### Syntax

-The input syntax for GTK documentation is markdown, in a flavor that is
-similar to what you see on gitlab or github. The markdown support for
-fragments that are extracted from sources is more limited than for
+The input syntax for GTK documentation is Markdown, in a flavor that is
+similar to what you see on GitLab or GitHub. The markdown support for
+fragments that are extracted from sources is identical to the one for
 freestanding chapters. As an exception, man pages for tools are currently
 maintained in docbook, since the conversion from markdown to docbook is
 losing too much of the expected formatting.

 In addition to typical markdown formatting such as \*emphasis\* or \_italics\_,
-gtk-doc supports a few abbreviations for cross-references and formatting:
+the GTK documentation supports additional link formats, like:

-`#ClassName`
+`[class@Namespace.ClassName]`
 : Creates a link to the docs for a class

-`function()`
- : Creates a link to the docs for a function
+`[method@Namespace.Method.name]`
+ : Creates a link to the docs for a method in a class

-`%constant`
- : Generates suitable markup for enum values or constants
+`[func@Namespace.function]`
+ : Creates a link to the docs for a global function

-### Sections
+For more information on the available link formats, see the gi-docgen
+documentation.

- - The "section" of each type must contain a name, to be referenced in the
-   `sections.txt` file; a title; and a short description. For instance:
+Every doc comment should start with a single-sentence paragraph that
+can serve as a summary of sorts (it will often be placed next to a
+link pointing to the full documentation for the symbol/class/etc).
+The summary should not include links.

-```c
-/**
- * SECTION:gtkshortcut
- * @Title: GtkShortcut
- * @Short_desc: A key shortcut
- *
- * ...
-```
+### Introspection annotations

-   For classes, the title should be the name of the class. While it's
-   possible to add section titles directly to the `sections.txt` file, this
-   is considered deprecated, and should not be done for newly written code.
- - For classes, the long description should contain an overview of the type;
-   what it does; typical use cases; and idiomatic examples of its use.
- - For widget classes, the long description of a section should also contain:
-   - special XML elements and attributes parsed by the class, in case of a
-     custom GtkBuildable implementation
-   - the CSS element name to be used by selectors
-   - the CSS selector hierarchy for children, in case of a composite widget
+The purpose of the annotations for function arguments, properties, signals,
+etc., is to describe the API in a machine readable way. The annotations
+are consumed by language bindings and by the documentation tools.
+
+For more information about the annotations used by GTK, you should refer to
+the [GObject Introspection documentation][gi-annotations].
+
+[gi-annotations]: https://gi.readthedocs.io/en/latest/annotations/giannotations.html
+
+### Type description
+
+Each type should be annotated with a description of what the type does.
+
+For classes, the description should contain an overview of the type;
+what it does; typical use cases; and idiomatic examples of its use.
+
+For widget classes, the description should also contain:
+
+  - special XML elements and attributes parsed by the class, in case of a
+    custom GtkBuildable implementation
+  - the CSS element name to be used by selectors
+  - the CSS selector hierarchy for children, in case of a composite widget
+  - the accessible role of the class
+
+Each section in a type description can have a heading; it's preferred to use
+second and third level headings only.

 ### Functions

@@ -155,17 +151,26 @@ Checks whether the widget is set to be visible or not.
 - Methods are special functions whose first argument is always the instance
   of a certain class. The instance argument for newly written code should be
   called `self`.
- - If a method is a setter or a getter for an object property, link the
-   property in the methods's description.
+ - If a method is a setter or a getter for an object property, you should
+   add an `(attributes org.gtk.Method.set_property=property-name)` or a
+   an `(attributes org.gtk.Method.get_property=property-name)` annotation
+   to the method's identifier
 - If a method changes one or more properties as side effect, link those
   properties in the method's description
- - If a method is a signal emitter, link the signal in the method's
-   description.
+ - If a method is a signal emitter, you should use the
+   `(attributes org.gtk.Method.signal=signal-name)` annotation in
+   the method's identifier
+
+### Arguments and return values
+
+ - Arguments should be descriptive, but short
+ - There is no need to mention the type of the argument
+ - Always annotate nullability, direction, and ownership transfer

 ### Signals

 - While GObject can introspect argument and return types for signals,
-   you should *always* document them with an explicit gtk-doc stanza.
+   you should *always* document them with an explicit documentation stanza.
 - The syntax for signal stanzas is similar to functions:

 ```c
@@ -181,12 +186,15 @@ Checks whether the widget is set to be visible or not.

 - While GObject properties contain text that can be extracted
   programmatically in order to build their documentation, you should
-   *always* document them with an explicit gtk-doc stanza. The text
+   *always* document them with an explicit documentation stanza. The text
   associated to the property is short and meant to be used when
   programmatically building user interfaces, and not for documentation
   purposes.
 - Always note if setting a property has side effects, like causing another
   property to change state.
+ - If the property has public accessors you should annotate it with
+   the `(attributes org.gtk.Property.set=setter_function)` and
+   `(attributes org.gtk.Property.get=getter_function)` attributes
 - The syntax for property documentation is:

 ```c
@@ -198,8 +206,9 @@ Checks whether the widget is set to be visible or not.

 ### Actions

- - Actions are new in GTK 4, and gtk-doc had to learn a new syntax
-   to document them:
+ - Actions are new in GTK 4, and describe an action associated to
+   a widget class
+ - The syntax for action documentation is:

 ```
 /**c
@@ -0,0 +1,18 @@
+----
+Title: Cairo interaction
+----
+
+## Functions to support using cairo
+
+[Cairo](http://cairographics.org) is a graphics library that supports vector
+graphics and image compositing that can be used with GTK.
+
+GDK does not wrap the Cairo API; instead it allows to create Cairo
+drawing contexts which can be used to draw on [class@Gdk.Surface]s.
+
+Additional functions allow use [struct@Gdk.Rectangle]s with Cairo
+and to use [struct@Gdk.RGBA], `GdkPixbuf`, and [class@Gdk.Surface]
+instances as sources for drawing operations.
+
+For more information on Cairo, please see the
+[Cairo API reference](https://www.cairographics.org/manual/).
@@ -1,89 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
-<!ENTITY version SYSTEM "version.xml">
-]>
-<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
-  <bookinfo>
-    <title>GDK 4 Reference Manual</title>
-    <releaseinfo>
-      This document is for the GDK 4 library, version &version;.
-      The latest versions can be found online at
-      <ulink role="online-location" url="https://developer.gnome.org/gdk4/">https://developer.gnome.org/gdk4/</ulink>.
-      If you are looking for the older GDK 3 series of libraries,
-      see <ulink role="online-location" url="https://developer.gnome.org/gdk3/">https://developer.gnome.org/gdk3/</ulink>.
-    </releaseinfo>
-  </bookinfo>
-
-  <chapter>
-    <title>API Reference</title>
-    <xi:include href="xml/general.xml" />
-    <xi:include href="xml/gdkdisplaymanager.xml" />
-    <xi:include href="xml/gdkdisplay.xml" />
-    <xi:include href="xml/gdkseat.xml" />
-    <xi:include href="xml/gdkdevice.xml" />
-    <section>
-      <xi:include href="xml/gdkdevicepad.xml" />
-    </section>
-    <xi:include href="xml/gdkmonitor.xml" />
-    <xi:include href="xml/regions.xml" />
-    <xi:include href="xml/textures.xml" />
-    <xi:include href="xml/gdkpaintable.xml" />
-    <xi:include href="xml/rgba_colors.xml" />
-    <xi:include href="xml/cursors.xml" />
-    <xi:include href="xml/gdksurface.xml" />
-    <xi:include href="xml/gdktoplevel.xml" />
-    <section>
-      <xi:include href="xml/gdktoplevellayout.xml" />
-      <xi:include href="xml/gdktoplevelsize.xml" />
-    </section>
-    <xi:include href="xml/gdkpopup.xml" />
-    <section>
-      <xi:include href="xml/gdkpopuplayout.xml" />
-    </section>
-    <xi:include href="xml/gdkframeclock.xml" />
-    <section>
-      <xi:include href="xml/gdkframetimings.xml" />
-    </section>
-    <xi:include href="xml/gdkdrawcontext.xml" />
-    <section>
-      <xi:include href="xml/gdkglcontext.xml" />
-      <xi:include href="xml/gdkvulkancontext.xml" />
-      <xi:include href="xml/gdkcairocontext.xml" />
-    </section>
-    <xi:include href="xml/events.xml" />
-    <xi:include href="xml/keys.xml" />
-    <xi:include href="xml/gdkclipboard.xml" />
-    <xi:include href="xml/dnd.xml" />
-    <xi:include href="xml/gdkcontentformats.xml" />
-    <xi:include href="xml/gdkcontentprovider.xml" />
-    <xi:include href="xml/gdkcontentserializer.xml" />
-    <xi:include href="xml/gdkcontentdeserializer.xml" />
-    <xi:include href="xml/pixbufs.xml" />
-    <xi:include href="xml/pango_interaction.xml" />
-    <xi:include href="xml/cairo_interaction.xml" />
-  </chapter>
-  <chapter>
-    <title>GDK Platform Support</title>
-    <xi:include href="xml/gdkapplaunchcontext.xml" />
-    <xi:include href="xml/x_interaction.xml" />
-    <xi:include href="xml/wayland_interaction.xml" />
-  </chapter>
-
-  <index id="api-index-full">
-    <title>Index of all symbols</title>
-    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-4-2" role="4.2">
-    <title>Index of new symbols in 4.2</title>
-    <xi:include href="xml/api-index-4.2.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-deprecated" role="deprecated">
-    <title>Index of deprecated symbols</title>
-    <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
-  </index>
-
-  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
-
-</book>
@@ -1,25 +0,0 @@
-
-<MACRO>
-<NAME>GDK_WINDOWING_X11</NAME>
-#define GDK_WINDOWING_X11
-</MACRO>
-
-<MACRO>
-<NAME>GDK_WINDOWING_WIN32</NAME>
-#define GDK_WINDOWING_WIN32
-</MACRO>
-
-<MACRO>
-<NAME>GDK_WINDOWING_MACOS</NAME>
-#define GDK_WINDOWING_MACOS
-</MACRO>
-
-<MACRO>
-<NAME>GDK_WINDOWING_WAYLAND</NAME>
-#define GDK_WINDOWING_WAYLAND
-</MACRO>
-
-<MACRO>
-<NAME>GDK_DISABLE_DEPRECATION_WARNINGS</NAME>
-#define GDK_DISABLE_DEPRECATION_WARNINGS
-</MACRO>
@@ -0,0 +1,23 @@
+[library]
+version = "@version@"
+browse_url = "https://gitlab.gnome.org/GNOME/gtk/"
+repository_url = "https://gitlab.gnome.org/GNOME/gtk.git"
+website_url = "https://www.gtk.org"
+authors = "GTK Development Team"
+logo_url = "gtk-logo.svg"
+license = "GPL-2.1-or-later"
+description = "The GTK toolkit"
+dependencies = [ "GObject-2.0" ]
+devhelp = true
+
+  [dependencies."GObject-2.0"]
+  name = "GObject"
+  description = "The base type system library"
+  docs_url = "https://developer.gnome.org/gobject/stable"
+
+[theme]
+name = "basic"
+show_index_summary = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/gtk/-/blob/master/"
@@ -0,0 +1,23 @@
+[library]
+version = "@version@"
+browse_url = "https://gitlab.gnome.org/GNOME/gtk/"
+repository_url = "https://gitlab.gnome.org/GNOME/gtk.git"
+website_url = "https://www.gtk.org"
+authors = "GTK Development Team"
+logo_url = "gtk-logo.svg"
+license = "GPL-2.1-or-later"
+description = "The GTK toolkit"
+dependencies = [ "GObject-2.0" ]
+devhelp = true
+
+  [dependencies."GObject-2.0"]
+  name = "GObject"
+  description = "The base type system library"
+  docs_url = "https://developer.gnome.org/gobject/stable"
+
+[theme]
+name = "basic"
+show_index_summary = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/gtk/-/blob/master/"
@@ -0,0 +1,97 @@
+[library]
+version = "@version@"
+browse_url = "https://gitlab.gnome.org/GNOME/gtk/"
+repository_url = "https://gitlab.gnome.org/GNOME/gtk.git"
+website_url = "https://www.gtk.org"
+authors = "GTK Development Team"
+logo_url = "gtk-logo.svg"
+license = "GPL-2.1-or-later"
+description = "The GTK toolkit"
+dependencies = [ "GObject-2.0", "cairo-1.0", "Pango-1.0", "GdkWayland-4.0",  "GdkX11-4.0" ]
+devhelp = true
+search_index = true
+
+  [dependencies."GObject-2.0"]
+  name = "GObject"
+  description = "The base type system library"
+  docs_url = "https://developer.gnome.org/gobject/stable"
+
+  [dependencies."cairo-1.0"]
+  name = "Cairo"
+  description = "A 2D graphics library with support for multiple output devices"
+  docs_url = "https://www.cairographics.org/manual/"
+
+  [dependencies."Pango-1.0"]
+  name = "Pango"
+  description = "Text shaping and rendering"
+  docs_url = "https://developer.gnome.org/pango/stable"
+
+  [dependencies."GdkWayland-4.0"]
+  name = "GdkWayland"
+  description = "GDK Wayland Backend"
+  docs_url = "https://gnome.pages.gitlab.gnome.org/gtk/gdk4-wayland/"
+
+  [dependencies."GdkX11-4.0"]
+  name = "GdkX11"
+  description = "GDK X11 Backend"
+  docs_url = "https://gnome.pages.gitlab.gnome.org/gtk/gdk4-x11/"
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/gtk/-/blob/master/"
+
+[extra]
+content_files = [
+  "keys.md",
+  "cairo.md",
+  "pango.md",
+  "wayland.md",
+  "x11.md",
+  "macos.md",
+]
+content_images = [
+  "images/gtk-logo.svg",
+  "images/rotated-text.png",
+  "images/default_cursor.png",
+  "images/help_cursor.png",
+  "images/pointer_cursor.png",
+  "images/context_menu_cursor.png",
+  "images/progress_cursor.png",
+  "images/wait_cursor.png",
+  "images/cell_cursor.png",
+  "images/crosshair_cursor.png",
+  "images/text_cursor.png",
+  "images/vertical_text_cursor.png",
+  "images/alias_cursor.png",
+  "images/copy_cursor.png",
+  "images/no_drop_cursor.png",
+  "images/move_cursor.png",
+  "images/not_allowed_cursor.png",
+  "images/grab_cursor.png",
+  "images/grabbing_cursor.png",
+  "images/all_scroll_cursor.png",
+  "images/col_resize_cursor.png",
+  "images/row_resize_cursor.png",
+  "images/n_resize_cursor.png",
+  "images/e_resize_cursor.png",
+  "images/s_resize_cursor.png",
+  "images/w_resize_cursor.png",
+  "images/ne_resize_cursor.png",
+  "images/nw_resize_cursor.png",
+  "images/sw_resize_cursor.png",
+  "images/se_resize_cursor.png",
+  "images/ew_resize_cursor.png",
+  "images/ns_resize_cursor.png",
+  "images/nesw_resize_cursor.png",
+  "images/nwse_resize_cursor.png",
+  "images/zoom_in_cursor.png",
+  "images/zoom_out_cursor.png",
+  "images/popup-anchors.png",
+  "images/popup-flip.png",
+  "images/popup-slide.png",
+]
+urlmap_file = "urlmap.js"
@@ -1,32 +0,0 @@
-gdk_app_launch_context_get_type
-gdk_clipboard_get_type
-gdk_content_deserializer_get_type
-gdk_content_formats_get_type
-gdk_content_provider_get_type
-gdk_content_serializer_get_type
-gdk_cursor_get_type
-gdk_device_get_type
-gdk_device_pad_get_type
-gdk_device_tool_get_type
-gdk_display_get_type
-gdk_display_manager_get_type
-gdk_drag_get_type
-gdk_drag_surface_get_type
-gdk_drop_get_type
-gdk_event_get_type
-gdk_frame_clock_get_type
-gdk_gl_context_get_type
-gdk_gl_texture_get_type
-gdk_memory_texture_get_type
-gdk_monitor_get_type
-gdk_paintable_get_type
-gdk_popup_get_type
-gdk_popup_layout_get_type
-gdk_rgba_get_type
-gdk_seat_get_type
-gdk_snapshot_get_type
-gdk_surface_get_type
-gdk_texture_get_type
-gdk_toplevel_get_type
-gdk_toplevel_layout_get_type
-gdk_vulkan_context_get_type
@@ -0,0 +1,16 @@
+Title: Library initialization and versioning
+
+The GDK and GTK headers annotate deprecated APIs in a way that produces
+compiler warnings if these deprecated APIs are used. The warnings
+can be turned off by defining the macro `GDK_DISABLE_DEPRECATION_WARNINGS`
+before including the `gdk.h` header.
+
+GDK and GTK also provide support for building applications against defined
+subsets of deprecated or new APIs. You can define the macro
+`GDK_VERSION_MIN_REQUIRED` to specify up to what version you want to receive
+warnings about deprecated APIs; and the macro `GDK_VERSION_MAX_ALLOWED` to
+specify the newest version whose API you want to use. If you attempt to use
+a function deprecated before the version of GTK specified in
+`GDK_VERSION_MIN_REQUIRED`, or a function introduced after the version of
+GTK specified in `GDK_VERSION_MAX_ALLOWED`, the compiler will warn you when
+building your code.
@@ -0,0 +1,138 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="128"
+   height="128"
+   id="svg6843"
+   sodipodi:version="0.32"
+   inkscape:version="0.92.4 5da689c313, 2019-01-14"
+   version="1.0"
+   sodipodi:docname="gtk-logo.svg"
+   inkscape:output_extension="org.inkscape.output.svg.inkscape"
+   inkscape:export-filename="/home/ebassi/Pictures/gtk-logo-256.png"
+   inkscape:export-xdpi="192"
+   inkscape:export-ydpi="192">
+  <defs
+     id="defs6845">
+    <inkscape:perspective
+       sodipodi:type="inkscape:persp3d"
+       inkscape:vp_x="-50 : 600 : 1"
+       inkscape:vp_y="0 : 1000 : 0"
+       inkscape:vp_z="700 : 600 : 1"
+       inkscape:persp3d-origin="300 : 400 : 1"
+       id="perspective13" />
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="2.8284271"
+     inkscape:cx="69.874353"
+     inkscape:cy="64.313526"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     inkscape:document-units="px"
+     inkscape:grid-bbox="true"
+     width="128px"
+     height="128px"
+     showguides="true"
+     inkscape:guide-bbox="true"
+     inkscape:window-width="1920"
+     inkscape:window-height="1016"
+     inkscape:window-x="0"
+     inkscape:window-y="27"
+     inkscape:window-maximized="1">
+    <inkscape:grid
+       type="xygrid"
+       id="grid7947" />
+  </sodipodi:namedview>
+  <metadata
+     id="metadata6848">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title />
+        <dc:date />
+        <dc:creator>
+          <cc:Agent>
+            <dc:title />
+          </cc:Agent>
+        </dc:creator>
+        <dc:rights>
+          <cc:Agent>
+            <dc:title />
+          </cc:Agent>
+        </dc:rights>
+        <dc:publisher>
+          <cc:Agent>
+            <dc:title />
+          </cc:Agent>
+        </dc:publisher>
+        <dc:identifier />
+        <dc:source />
+        <dc:relation />
+        <dc:language />
+        <dc:subject>
+          <rdf:Bag />
+        </dc:subject>
+        <dc:coverage />
+        <dc:description />
+        <dc:contributor>
+          <cc:Agent>
+            <dc:title />
+          </cc:Agent>
+        </dc:contributor>
+        <cc:license
+           rdf:resource="" />
+      </cc:Work>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     id="layer1"
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer">
+    <path
+       sodipodi:nodetypes="ccccc"
+       id="path6976"
+       d="M 20.88413,30.82696 L 53.816977,55.527708 L 107.33282,39.060543 L 70.587303,17.177763 L 20.88413,30.82696 z"
+       style="fill:#729fcf;fill-opacity:1;fill-rule:evenodd;stroke:#ffffff;stroke-width:2.12364459;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;display:inline" />
+    <path
+       id="path6978"
+       d="M 22.94243,82.287118 L 20.88413,30.82696 L 53.816977,55.527708 L 53.816977,111.10486 L 22.94243,82.287118 z"
+       style="fill:#e40000;fill-opacity:1;fill-rule:evenodd;stroke:#ffffff;stroke-width:2.12364459;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;display:inline" />
+    <path
+       id="path6980"
+       d="M 53.816977,111.10486 L 103.21619,90.5207 L 107.33282,39.060543 L 53.816977,55.527708 L 53.816977,111.10486 z"
+       style="fill:#7fe719;fill-opacity:1;fill-rule:evenodd;stroke:#ffffff;stroke-width:2.12364459;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;display:inline" />
+    <path
+       sodipodi:nodetypes="ccc"
+       id="path6982"
+       d="M 23.216626,81.319479 L 70.48573,67.361442 L 103.38422,90.444516"
+       style="opacity:1;fill:none;fill-rule:evenodd;stroke:#ffffff;stroke-width:1.25;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
+    <path
+       sodipodi:nodetypes="cc"
+       id="path6984"
+       d="M 70.434539,17.875593 L 70.434539,66.984877"
+       style="opacity:1;fill:#babdb6;fill-rule:evenodd;stroke:#ffffff;stroke-width:1.25;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
+  </g>
+</svg>
@@ -0,0 +1,113 @@
+Title: Key Values
+
+## Functions for manipulating keyboard codes
+
+Key values are the codes which are sent whenever a key is pressed or released.
+They are included in the data contained in a key press or release #GdkEvent.
+The complete list of key values can be found in the `gdk/gdkkeysyms.h` header
+file.
+
+Key values are regularly updated from the upstream X.org X11 implementation,
+so new values are added regularly. They will be prefixed with GDK_KEY_ rather
+than XF86XK_ or XK_ (for older symbols).
+
+Key values can be converted into a string representation using
+gdk_keyval_name(). The reverse function, converting a string to a key value,
+is provided by gdk_keyval_from_name().
+
+The case of key values can be determined using gdk_keyval_is_upper() and
+gdk_keyval_is_lower(). Key values can be converted to upper or lower case
+using gdk_keyval_to_upper() and gdk_keyval_to_lower().
+
+When it makes sense, key values can be converted to and from
+Unicode characters with gdk_keyval_to_unicode() and gdk_unicode_to_keyval().
+
+## Key groups
+
+At the lowest level, physical keys on the keyboard are represented by
+numeric keycodes, and GDK knows how to translate these keycodes into
+key values according to the configured keyboard layout and the current
+state of the keyboard. In the GDK api, the mapping from keycodes to key
+values is available via [`method@Gdk.Display.map_keycode`], and the reverse
+mapping is available via [`method@Gdk.Display.map_keyval`]. The results of
+these functions are returned in [struct@Gdk.KeymapKey] structures.
+
+You can think of a [struct@Gdk.KeymapKey] as a representation of a symbol
+printed on a physical keyboard key. That is, it contains three pieces of
+information:
+
+  1. first, it contains the hardware keycode; this is an identifying number
+    for a physical key
+  1. second, it contains the “level” of the key. The level indicates which
+    symbol on the key will be used, in a vertical direction. So on a standard
+    US keyboard, the key with the number “1“ on it also has the exclamation
+    point (”!”) character on it. The level indicates whether to use the “1”
+    or the “!” symbol. The letter keys are considered to have a lowercase
+    letter at level 0, and an uppercase letter at level 1, though normally
+    only the uppercase letter is printed on the key
+  1. third, the #GdkKeymapKey contains a group; groups are not used on
+     standard US keyboards, but are used in many other countries. On a
+     keyboard with groups, there can be 3 or 4 symbols printed on a single
+     key. The group indicates movement in a horizontal direction. Usually
+     groups are used for two different languages. In 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.
+
+When GDK creates a key event in order to deliver a key press or release,
+it first converts the current keyboard state into an effective group and
+level. This is done via a set of rules that varies widely according to
+type of keyboard and user configuration. The input to this translation
+consists of the hardware keycode pressed, the active modifiers, and the
+active group. It then applies the appropriate rules, and returns the
+group/level to be used to index the keymap, along with the modifiers
+which did not affect the group and level. i.e. it returns “unconsumed
+modifiers.” The keyboard group may differ from the effective group used
+for lookups because some keys don't have multiple groups - e.g. the
+<kbd>Enter</kbd> key is always in group 0 regardless of keyboard state.
+
+The results of the translation, including the keyval, are all included
+in the key event and can be obtained via [class@Gdk.KeyEvent] getters.
+
+### Consumed modifiers
+
+The `consumed_modifiers` in a key event are modifiers that should be masked
+out from @state when comparing this key press to a hot key. For instance,
+on a US keyboard, the `plus` symbol is shifted, so when comparing a key
+press to a `<Control>plus` accelerator `<Shift>` should be masked out.
+
+```c
+// We want to ignore irrelevant modifiers like ScrollLock
+#define ALL_ACCELS_MASK (GDK_CONTROL_MASK | GDK_SHIFT_MASK | GDK_ALT_MASK)
+state = gdk_event_get_modifier_state (event);
+gdk_keymap_translate_keyboard_state (keymap,
+                                     gdk_key_event_get_keycode (event),
+                                     state,
+                                     gdk_key_event_get_group (event),
+                                     &keyval, NULL, NULL, &consumed);
+if (keyval == GDK_PLUS &&
+    (state & ~consumed & ALL_ACCELS_MASK) == GDK_CONTROL_MASK)
+  // Control was pressed
+```
+
+An older interpretation of `consumed_modifiers` was that it contained
+all modifiers that might affect the translation of the key;
+this allowed accelerators to be stored with irrelevant consumed
+modifiers, by doing:
+
+```c
+// XXX Don’t do this XXX
+if (keyval == accel_keyval &&
+    (state & ~consumed & ALL_ACCELS_MASK) == (accel_mods & ~consumed))
+  // Accelerator was pressed
+```
+
+However, this did not work if multi-modifier combinations were
+used in the keymap, since, for instance, `<Control>` would be
+masked out even if only `<Control><Alt>` was used in
+the keymap. To support this usage as well as well as possible, all single
+modifier combinations that could affect the key for any combination
+of modifiers will be returned in `consumed_modifiers`; multi-modifier
+combinations are returned only when actually found in `state`. When
+you store accelerators, you should always store them with consumed
+modifiers removed. Store `<Control>plus`, not `<Control><Shift>plus`.
@@ -0,0 +1,58 @@
+Title: macOS Interaction
+
+## macOS backend-specific functions
+
+The functions in this section are specific to the GDK macOS backend.
+To use them, you need to include the `<gdk/macos/gdkmacos.h>` header and
+use the macOS-specific pkg-config `gtk4-macos` file to build your
+application.
+
+## Checking for the macOS backend
+
+GDK can be built with support for multiple backends, which means you will
+need to perform both compile time *and* run time checks if you wish to call
+backend-specific API; for instance, the code sample below will guard the
+calls to different backends, and error out on unsupported windowing systems:
+
+```c
+#ifdef GDK_WINDOWING_MACOS
+#include <gdk/macos/gdkmacos.h>
+#endif
+#ifdef GDK_WINDOWING_WAYLAND
+#include <gdk/wayland/gdkwayland.h>
+#endif
+#ifdef GDK_WINDOWING_X11
+#include <gdk/x11/gdkx.h>
+#endif
+
+#ifdef GDK_WINDOWING_MACOS
+  if (GDK_IS_MACOS_DISPLAY (display))
+    {
+      // make macOS-specific calls here
+    }
+  else
+#endif
+#ifdef GDK_WINDOWING_WAYLAND
+  if (GTK_IS_WAYLAND_DISPLAY (display))
+    {
+      // make Wayland-specific calls here
+    }
+  else
+#endif
+#ifdef GDK_WINDOWING_X11
+  if (GDK_IS_X11_DISPLAY (display))
+    {
+      // make X11-specific calls here
+    }
+  else
+#endif
+  g_error ("Unsupported GDK backend");
+```
+
+The compile time check is performed by using the `GDK_WINDOWING_*`
+pre-processor symbols; there is one defined for each windowing system
+backend built into GDK. For Wayland, the symbol is `GDK_WINDOWING_MACOS`.
+
+The run time check is performed by looking at the type of the
+[class@Gdk.Display] object. For Wayland, the display objects will be of type
+`GdkMacosDisplay`.
@@ -1,190 +1,74 @@
-private_headers = [
-  'gdk-autocleanup.h',
-  'gdk-private.h',
-  'gdkapplaunchcontextprivate.h',
-  'gdkcairocontextprivate.h',
-  'gdkcairoprivate.h',
-  'gdkclipboardprivate.h',
-  'gdkcontentformatsprivate.h',
-  'gdkcontentproviderprivate.h',
-  'gdkcursorprivate.h',
-  'gdkdebug.h',
-  'gdkdevicepadprivate.h',
-  'gdkdeviceprivate.h',
-  'gdkdevicetoolprivate.h',
-  'gdkdisplaymanagerprivate.h',
-  'gdkdisplayprivate.h',
-  'gdkdndprivate.h',
-  'gdkdragprivate.h',
-  'gdkdragsurfaceprivate.h',
-  'gdkdrawcontextprivate.h',
-  'gdkdropprivate.h',
-  'gdkeventsprivate.h',
-  'gdkframeclockidleprivate.h',
-  'gdkframeclockprivate.h',
-  'gdkglcontextprivate.h',
-  'gdkgltextureprivate.h',
-  'gdkinternals.h',
-  'gdkintl.h',
-  'gdkkeysprivate.h',
-  'gdkkeysyms.h',
-  'gdkmarshalers.h',
-  'gdkmemorytextureprivate.h',
-  'gdkmonitorprivate.h',
-  'gdkpipeiostreamprivate.h',
-  'gdkpopupprivate.h',
-  'gdkprofilerprivate.h',
-  'gdkrgbaprivate.h',
-  'gdkscreenprivate.h',
-  'gdkseatdefaultprivate.h',
-  'gdkseatprivate.h',
-  'gdksnapshotprivate.h',
-  'gdksurfaceimpl.h',
-  'gdksurfaceprivate.h',
-  'gdktextureprivate.h',
-  'gdktoplevelprivate.h',
-  'gdktoplevelsizeprivate.h',
-  'gdkvulkancontextprivate.h',
-
-  'filetransferportalprivate.h',
-  'gdkconstructor.h',
-  'keyname-table.h',
-
-  # gdk/x11
-  'gdkasync.h',
-  'gdkcairocontext-x11.h',
-  'gdkclipboard-x11.h',
-  'gdkdevice-xi2-private.h',
-  'gdkdevicemanagerprivate-core.h',
-  'gdkdisplay-x11.h',
-  'gdkeventsource.h',
-  'gdkeventtranslator.h',
-  'gdkglcontext-x11.h',
-  'gdkkeys-x11.h',
-  'gdkmonitor-x11.h',
-  'gdkprivate-x11.h',
-  'gdkscreen-x11.h',
-  'gdkselectioninputstream-x11.h',
-  'gdkselectionoutputstream-x11.h',
-  'gdksurface-x11.h',
-  'gdktextlistconverter-x11.h',
-  'gdkvisual-x11.h',
-  'gdkvulkancontext-x11.h',
-  'gdkx-autocleanups.h',
-  'MwmUtil.h',
-  'xsettings-client.h',
-
-  # gdk/wayland
-  'gdkcairocontext-wayland.h',
-  'gdkclipboard-wayland.h',
-  'gdkdevice-wayland-private.h',
-  'gdkdisplay-wayland.h',
-  'gdkglcontext-wayland.h',
-  'gdkmonitor-wayland.h',
-  'gdkprimary-wayland.h',
-  'gdkprivate-wayland.h',
-  'gdkseat-wayland.h',
-  'gdksurface-wayland.h',
-  'gdkvulkancontext-wayland.h',
-  'wm-button-layout-translation.h',
-  'gtk-primary-selection-client-protocol.h',
-  'gtk-shell-client-protocol.h',
-  'idle-inhibit-unstable-v1-client-protocol.h',
-  'keyboard-shortcuts-inhibit-unstable-v1-client-protocol.h',
-  'pointer-gestures-unstable-v1-client-protocol.h',
-  'primary-selection-unstable-v1-client-protocol.h',
-  'server-decoration-client-protocol.h',
-  'tablet-unstable-v2-client-protocol.h',
-  'xdg-foreign-unstable-v1-client-protocol.h',
-  'xdg-shell-unstable-v6-client-protocol.h',
-  'xdg-output-unstable-v1-client-protocol.h',
-  'xdg-shell-client-protocol.h',
-  'xdg-shell-unstable-v6-client-protocol.h',
-  'wayland-cursor.h',
-  'os-compatibility.h',
-  'xcursor.h',
-
-  'broadway',
-  'wayland/cursor',
-  'macos',
-  'win32',
+expand_content_md_files = [
 ]

-images = [
-  'images/rotated-text.png',
-  'images/default_cursor.png',
-  'images/help_cursor.png',
-  'images/pointer_cursor.png',
-  'images/context_menu_cursor.png',
-  'images/progress_cursor.png',
-  'images/wait_cursor.png',
-  'images/cell_cursor.png',
-  'images/crosshair_cursor.png',
-  'images/text_cursor.png',
-  'images/vertical_text_cursor.png',
-  'images/alias_cursor.png',
-  'images/copy_cursor.png',
-  'images/no_drop_cursor.png',
-  'images/move_cursor.png',
-  'images/not_allowed_cursor.png',
-  'images/grab_cursor.png',
-  'images/grabbing_cursor.png',
-  'images/all_scroll_cursor.png',
-  'images/col_resize_cursor.png',
-  'images/row_resize_cursor.png',
-  'images/n_resize_cursor.png',
-  'images/e_resize_cursor.png',
-  'images/s_resize_cursor.png',
-  'images/w_resize_cursor.png',
-  'images/ne_resize_cursor.png',
-  'images/nw_resize_cursor.png',
-  'images/sw_resize_cursor.png',
-  'images/se_resize_cursor.png',
-  'images/ew_resize_cursor.png',
-  'images/ns_resize_cursor.png',
-  'images/nesw_resize_cursor.png',
-  'images/nwse_resize_cursor.png',
-  'images/zoom_in_cursor.png',
-  'images/zoom_out_cursor.png',
-  'images/popup-anchors.png',
-  'images/popup-flip.png',
-  'images/popup-slide.png',
-]
-
-src_dir = [ gdkinc ]
-
-if x11_enabled
-  src_dir += [ gdkx11_inc ]
-endif
-
-if wayland_enabled
-  src_dir += [ gdkwayland_inc ]
-endif
+gdk4_toml = configure_file(input: 'gdk4.toml.in', output: 'gdk4.toml', configuration: toml_conf)
+gdk4x11_toml = configure_file(input: 'gdk4-x11.toml.in', output: 'gdk4-x11.toml', configuration: toml_conf)
+gdk4wayland_toml = configure_file(input: 'gdk4-wayland.toml.in', output: 'gdk4-wayland.toml', configuration: toml_conf)

 if get_option('gtk_doc')
-  configure_file(input: 'version.xml.in', output: 'version.xml', configuration: version_conf)
-
-  gnome.gtkdoc('gdk4',
-    mode: 'none',
-    main_xml: 'gdk4-docs.xml',
-    src_dir: src_dir,
-    dependencies: libgtk_dep,
-    gobject_typesfile: join_paths(meson.current_source_dir(), 'gdk4.types'),
-    scan_args: [
-      '--ignore-decorators=_GDK_EXTERN|G_GNUC_WARN_UNUSED_RESULT',
-      '--ignore-headers=' + ' '.join(private_headers),
+  custom_target('gdk4-doc',
+    input: [ gdk4_toml, gdk_gir[0] ],
+    output: 'gdk4',
+    command: [
+      gidocgen,
+      'generate',
+      '--quiet',
+      '--add-include-path=@0@'.format(meson.current_build_dir() / '../../../gtk'),
+      '--config=@INPUT0@',
+      '--output-dir=@OUTPUT@',
+      '--no-namespace-dir',
+      '--content-dir=@0@'.format(meson.current_source_dir()),
+      '@INPUT1@',
    ],
-    mkdb_args: [
-      '--ignore-files=' + ' '.join(private_headers),
-    ],
-    fixxref_args: [
-      '--html-dir=@0@'.format(docpath),
-      '--extra-dir=@0@'.format(join_paths(glib_docpath, 'glib')),
-      '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gobject')),
-      '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gio')),
-      '--extra-dir=@0@'.format(cairo_docpath),
-    ],
-    html_assets: images,
+    depend_files: [ expand_content_md_files ],
+    build_by_default: true,
    install: true,
+    install_dir: docs_dir,
  )
+
+  if x11_enabled
+    custom_target('gdk4-x11-doc',
+      input: [ gdk4x11_toml, gdk_x11_gir[0] ],
+      output: 'gdk4-x11',
+      command: [
+        gidocgen,
+        'generate',
+        '--quiet',
+        '--add-include-path=@0@'.format(meson.current_build_dir() / '../../../gtk'),
+        '--config=@INPUT0@',
+        '--output-dir=@OUTPUT@',
+        '--no-namespace-dir',
+        '--content-dir=@0@'.format(meson.current_source_dir()),
+        '@INPUT1@',
+      ],
+      depends: [ gdk_gir[0] ],
+      depend_files: [ ],
+      build_by_default: true,
+      install: true,
+      install_dir: docs_dir,
+    )
+  endif
+
+  if wayland_enabled
+    custom_target('gdk4-wayland-doc',
+      input: [ gdk4wayland_toml, gdk_wayland_gir[0] ],
+      output: 'gdk4-wayland',
+      command: [
+        gidocgen,
+        'generate',
+        '--quiet',
+        '--add-include-path=@0@'.format(meson.current_build_dir() / '../../../gtk'),
+        '--config=@INPUT0@',
+        '--output-dir=@OUTPUT@',
+        '--no-namespace-dir',
+        '--content-dir=@0@'.format(meson.current_source_dir()),
+        '@INPUT1@',
+      ],
+      depends: [ gdk_gir[0] ],
+      depend_files: [ ],
+      build_by_default: true,
+      install: true,
+      install_dir: docs_dir,
+    )
+  endif
 endif
@@ -0,0 +1,94 @@
+ Title: Pango Interaction
+
+Pango is the text layout system used by GDK and GTK. The functions
+and types in this section are used to obtain clip regions for
+`PangoLayout`s, and to get `PangoContext`s that can be used with
+GDK.
+
+## Using Pango in GDK
+
+Creating a `PangoLayout` object is the first step in rendering text,
+and requires getting a handle to a `PangoContext`. For GTK programs,
+you’ll usually want to use [method@Gtk.Widget.get_pango_context], or
+[method@Gtk.Widget.create_pango_layout]. Once you have a `PangoLayout`,
+you can set the text and attributes of it with Pango functions like
+[method@Pango.Layout.set_text] and get its size with
+[method@Pango.Layout.get_size].
+
+*Note*: Pango uses a fixed point system internally, so converting
+between Pango units and pixels using `PANGO_SCALE` or the `PANGO_PIXELS()`
+macro.
+
+Rendering a Pango layout is done most simply with [func@PangoCairo.show_layout];
+you can also draw pieces of the layout with [func@PangoCairo.show_layout_line].
+
+### Draw transformed text with Pango and cairo
+
+```c
+#define RADIUS 100
+#define N_WORDS 10
+#define FONT "Sans Bold 18"
+
+PangoContext *context;
+PangoLayout *layout;
+PangoFontDescription *desc;
+
+double radius;
+int width, height;
+int i;
+
+// Set up a transformation matrix so that the user space coordinates for
+// where we are drawing are [-RADIUS, RADIUS], [-RADIUS, RADIUS]
+// We first center, then change the scale
+
+width = gdk_surface_get_width (surface);
+height = gdk_surface_get_height (surface);
+radius = MIN (width, height) / 2.;
+
+cairo_translate (cr,
+                 radius + (width - 2 * radius) / 2,
+                 radius + (height - 2 * radius) / 2);
+                 cairo_scale (cr, radius / RADIUS, radius / RADIUS);
+
+// Create a PangoLayout, set the font and text
+context = gdk_pango_context_get_for_display (display);
+layout = pango_layout_new (context);
+pango_layout_set_text (layout, "Text", -1);
+desc = pango_font_description_from_string (FONT);
+pango_layout_set_font_description (layout, desc);
+pango_font_description_free (desc);
+
+// Draw the layout N_WORDS times in a circle
+for (i = 0; i < N_WORDS; i++)
+  {
+    double red, green, blue;
+    double angle = 2 * G_PI * i / n_words;
+
+    cairo_save (cr);
+
+    // Gradient from red at angle == 60 to blue at angle == 300
+    red = (1 + cos (angle - 60)) / 2;
+    green = 0;
+    blue = 1 - red;
+
+    cairo_set_source_rgb (cr, red, green, blue);
+    cairo_rotate (cr, angle);
+
+    // Inform Pango to re-layout the text with the new transformation matrix
+    pango_cairo_update_layout (cr, layout);
+
+    pango_layout_get_size (layout, &width, &height);
+
+    cairo_move_to (cr, - width / 2 / PANGO_SCALE, - DEFAULT_TEXT_RADIUS);
+    pango_cairo_show_layout (cr, layout);
+
+    cairo_restore (cr);
+  }
+
+g_object_unref (layout);
+g_object_unref (context);
+```
+
+The example code above will yield the following result:
+
+![](rotated-text.png)
@@ -0,0 +1,13 @@
+// SPDX-FileCopyrightText: 2021 GNOME Foundation
+// SPDX-License-Identifier: LGPL-2.1-or-later
+
+// A map between namespaces and base URLs for their online documentation
+baseURLs = [
+    [ 'Gdk', 'https://gnome.pages.gitlab.gnome.org/gtk/gdk4/' ],
+    [ 'GdkWayland', 'https://gnome.pages.gitlab.gnome.org/gtk/gdk4-wayland/' ],
+    [ 'GdkX11', 'https://gnome.pages.gitlab.gnome.org/gtk/gdk4-x11/' ],
+    [ 'Gsk', 'https://gnome.pages.gitlab.gnome.org/gtk/gsk4/' ],
+    [ 'Gtk', 'https://gnome.pages.gitlab.gnome.org/gtk/gtk4/' ],
+    [ 'Pango', 'https://gnome.pages/gitlab.gnome.org/pango/pango/' ],
+    [ 'PangoCairo', 'https://gnome.pages.gitlab.gnome.org/pango/pangocairo/' ],
+]
@@ -1 +0,0 @@
-@GTK_VERSION@
@@ -0,0 +1,48 @@
+Title: Wayland Interaction
+
+## Wayland backend-specific functions
+
+The functions in this section are specific to the GDK Wayland backend.
+To use them, you need to include the `<gdk/wayland/gdkwayland.h>` header and
+use the Wayland-specific pkg-config `gtk4-wayland` file to build your
+application.
+
+## Checking for the Wayland backend
+
+GDK can be built with support for multiple backends, which means you will
+need to perform both compile time *and* run time checks if you wish to call
+backend-specific API; for instance, the code sample below will guard the
+calls to different backends, and error out on unsupported windowing systems:
+
+```c
+#ifdef GDK_WINDOWING_WAYLAND
+#include <gdk/wayland/gdkwayland.h>
+#endif
+#ifdef GDK_WINDOWING_X11
+#include <gdk/x11/gdkx.h>
+#endif
+
+#ifdef GDK_WINDOWING_WAYLAND
+  if (GTK_IS_WAYLAND_DISPLAY (display))
+    {
+      // make Wayland-specific calls here
+    }
+  else
+#endif
+#ifdef GDK_WINDOWING_X11
+  if (GDK_IS_X11_DISPLAY (display))
+    {
+      // make X11-specific calls here
+    }
+  else
+#endif
+  g_error ("Unsupported GDK backend");
+```
+
+The compile time check is performed by using the `GDK_WINDOWING_*`
+pre-processor symbols; there is one defined for each windowing system
+backend built into GDK. For Wayland, the symbol is `GDK_WINDOWING_WAYLAND`.
+
+The run time check is performed by looking at the type of the
+[class@Gdk.Display] object. For Wayland, the display objects will be of type
+`GdkWaylandDisplay`.
@@ -0,0 +1,47 @@
+Title: X Window System Interaction
+
+## X backend-specific functions
+
+The functions in this section are specific to the GDK X11 backend.
+To use them, you need to include the `<gdk/x11/gdkx.h>` header and use
+the X11-specific pkg-config file `gtk4-x11` to build your application.
+
+## Checking for the X11 backend
+
+GDK can be built with support for multiple backends, which means you will
+need to perform both compile time *and* run time checks if you wish to call
+backend-specific API; for instance, the code sample below will guard the
+calls to different backends, and error out on unsupported windowing systems:
+
+```c
+#ifdef GDK_WINDOWING_X11
+#include <gdk/x11/gdkx.h>
+#endif
+#ifdef GDK_WINDOWING_WAYLAND
+#include <gdk/wayland/gdkwayland.h>
+#endif
+
+#ifdef GDK_WINDOWING_X11
+  if (GDK_IS_X11_DISPLAY (display))
+    {
+      // make X11-specific calls here
+    }
+  else
+#endif
+#ifdef GDK_WINDOWING_WAYLAND
+  if (GTK_IS_WAYLAND_DISPLAY (display))
+    {
+      // make Wayland-specific calls here
+    }
+  else
+#endif
+  g_error ("Unsupported GDK backend");
+```
+
+The compile time check is performed by using the `GDK_WINDOWING_*`
+pre-processor symbols; there is one defined for each windowing system
+backend built into GDK. For X11, the symbol is `GDK_WINDOWING_X11`.
+
+The run time check is performed by looking at the type of the
+[class@Gdk.Display] object. For X11, the display objects will be of type
+`GdkX11Display`.
@@ -1,33 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
-<!ENTITY version SYSTEM "version.xml">
-]>
-<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
-  <bookinfo>
-    <title>GSK 4 Reference Manual</title>
-    <releaseinfo>
-      This document is for the GSK 4 library, version &version;
-      The latest versions can be found online at
-      <ulink role="online-location" url="https://developer.gnome.org/gsk4/">https://developer.gnome.org/gsk4/</ulink>.
-    </releaseinfo>
-  </bookinfo>
-
-  <reference id="reference">
-    <title>API Reference</title>
-    <xi:include href="xml/GskRenderer.xml" />
-    <xi:include href="xml/GskRenderNode.xml" />
-    <xi:include href="xml/GskRoundedRect.xml" />
-    <xi:include href="xml/GskTransform.xml" />
-    <xi:include href="xml/GskGLShader.xml" />
-  </reference>
-
-  <index id="api-index-full">
-    <title>Index of all symbols</title>
-    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
-  </index>
-
-  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
-
-</book>
@@ -1,399 +0,0 @@
-<SECTION>
-<FILE>GskRenderer</FILE>
-GskRenderer
-gsk_renderer_get_surface
-gsk_renderer_realize
-gsk_renderer_unrealize
-gsk_renderer_is_realized
-gsk_renderer_render
-gsk_renderer_render_texture
-<SUBSECTION>
-gsk_renderer_new_for_surface
-gsk_gl_renderer_new
-gsk_cairo_renderer_new
-gsk_vulkan_renderer_new
-gsk_broadway_renderer_new
-<SUBSECTION Standard>
-GSK_IS_RENDERER
-GSK_RENDERER
-GSK_TYPE_RENDERER
-GskRendererClass
-gsk_renderer_get_type
-GSK_TYPE_SCALING_FILTER
-GSK_BROADWAY_RENDERER
-GSK_BROADWAY_RENDERER_CLASS
-GSK_BROADWAY_RENDERER_GET_CLASS
-GSK_IS_BROADWAY_RENDERER
-GSK_IS_BROADWAY_RENDERER_CLASS
-GSK_TYPE_BROADWAY_RENDERER
-GskBroadwayRenderer
-GskBroadwayRendererClass
-GSK_CAIRO_RENDERER
-GSK_CAIRO_RENDERER_CLASS
-GSK_CAIRO_RENDERER_GET_CLASS
-GSK_IS_CAIRO_RENDERER
-GSK_IS_CAIRO_RENDERER_CLASS
-GSK_TYPE_CAIRO_RENDERER
-GskCairoRenderer
-GskCairoRendererClass
-GSK_GL_RENDERER
-GSK_GL_RENDERER_CLASS
-GSK_GL_RENDERER_GET_CLASS
-GSK_IS_GL_RENDERER
-GSK_IS_GL_RENDERER_CLASS
-GSK_TYPE_GL_RENDERER
-GskGLRenderer
-GskGLRendererClass
-gsk_gl_renderer_get_type
-GSK_VULKAN_RENDERER
-GSK_VULKAN_RENDERER_CLASS
-GSK_VULKAN_RENDERER_GET_CLASS
-GSK_IS_VULKAN_RENDERER
-GSK_IS_VULKAN_RENDERER_CLASS
-GSK_TYPE_VULKAN_RENDERER
-GskVulkanRenderer
-GskVulkanRendererClass
-gsk_vulkan_renderer_get_type
-</SECTION>
-
-<SECTION>
-<FILE>GskRenderNode</FILE>
-GskRenderNode
-GskBlendNode
-GskBlurNode
-GskBorderNode
-GskCairoNode
-GskClipNode
-GskColorMatrixNode
-GskColorNode
-GskConicGradientNode
-GskContainerNode
-GskCrossFadeNode
-GskDebugNode
-GskInsetShadowNode
-GskLinearGradientNode
-GskRadialGradientNode
-GskOpacityNode
-GskOutsetShadowNode
-GskRepeatingLinearGradientNode
-GskRepeatingRadialGradientNode
-GskRepeatNode
-GskRoundedClipNode
-GskShadowNode
-GskTextNode
-GskTextureNode
-GskTransformNode
-GskGLShaderNode
-gsk_render_node_ref
-gsk_render_node_unref
-GskRenderNodeType
-gsk_render_node_get_node_type
-gsk_render_node_draw
-GskSerializationError
-GskParseErrorFunc
-GskParseLocation
-gsk_render_node_serialize
-gsk_render_node_deserialize
-gsk_render_node_write_to_file
-GskScalingFilter
-gsk_render_node_get_bounds
-
-<SUBSECTION>
-gsk_color_node_new
-gsk_color_node_get_color
-gsk_texture_node_new
-gsk_texture_node_get_texture
-<SUBSECTION>
-GskColorStop
-gsk_linear_gradient_node_new
-gsk_repeating_linear_gradient_node_new
-gsk_linear_gradient_node_get_start
-gsk_linear_gradient_node_get_end
-gsk_linear_gradient_node_get_n_color_stops
-gsk_linear_gradient_node_get_color_stops
-<SUBSECTION>
-gsk_radial_gradient_node_new
-gsk_repeating_radial_gradient_node_new
-gsk_radial_gradient_node_get_n_color_stops
-gsk_radial_gradient_node_get_color_stops
-gsk_radial_gradient_node_get_start
-gsk_radial_gradient_node_get_end
-gsk_radial_gradient_node_get_hradius
-gsk_radial_gradient_node_get_vradius
-gsk_radial_gradient_node_get_center
-<SUBSECTION>
-gsk_conic_gradient_node_new
-gsk_conic_gradient_node_get_n_color_stops
-gsk_conic_gradient_node_get_color_stops
-gsk_conic_gradient_node_get_center
-gsk_conic_gradient_node_get_rotation
-<SUBSECTION>
-gsk_border_node_new
-gsk_border_node_get_outline
-gsk_border_node_get_widths
-gsk_border_node_get_colors
-<SUBSECTION>
-gsk_inset_shadow_node_new
-gsk_inset_shadow_node_get_outline
-gsk_inset_shadow_node_get_color
-gsk_inset_shadow_node_get_dx
-gsk_inset_shadow_node_get_dy
-gsk_inset_shadow_node_get_spread
-gsk_inset_shadow_node_get_blur_radius
-<SUBSECTION>
-gsk_outset_shadow_node_new
-gsk_outset_shadow_node_get_outline
-gsk_outset_shadow_node_get_color
-gsk_outset_shadow_node_get_dx
-gsk_outset_shadow_node_get_dy
-gsk_outset_shadow_node_get_spread
-gsk_outset_shadow_node_get_blur_radius
-<SUBSECTION>
-gsk_cairo_node_new
-gsk_cairo_node_get_draw_context
-gsk_cairo_node_get_surface
-<SUBSECTION>
-gsk_container_node_new
-gsk_container_node_get_n_children
-gsk_container_node_get_child
-<SUBSECTION>
-gsk_transform_node_new
-gsk_transform_node_get_child
-gsk_transform_node_get_transform
-<SUBSECTION>
-gsk_opacity_node_new
-gsk_opacity_node_get_child
-gsk_opacity_node_get_opacity
-<SUBSECTION>
-gsk_color_matrix_node_new
-gsk_color_matrix_node_get_child
-gsk_color_matrix_node_get_color_matrix
-gsk_color_matrix_node_get_color_offset
-<SUBSECTION>
-gsk_repeat_node_new
-gsk_repeat_node_get_child
-gsk_repeat_node_get_child_bounds
-<SUBSECTION>
-gsk_clip_node_new
-gsk_clip_node_get_child
-gsk_clip_node_get_clip
-<SUBSECTION>
-gsk_rounded_clip_node_new
-gsk_rounded_clip_node_get_child
-gsk_rounded_clip_node_get_clip
-<SUBSECTION>
-GskShadow
-gsk_shadow_node_new
-gsk_shadow_node_get_shadow
-gsk_shadow_node_get_n_shadows
-gsk_shadow_node_get_child
-<SUBSECTION>
-GskBlendMode
-gsk_blend_node_new
-gsk_blend_node_get_bottom_child
-gsk_blend_node_get_top_child
-gsk_blend_node_get_blend_mode
-<SUBSECTION>
-gsk_cross_fade_node_new
-gsk_cross_fade_node_get_start_child
-gsk_cross_fade_node_get_end_child
-gsk_cross_fade_node_get_progress
-<SUBSECTION>
-gsk_text_node_new
-gsk_text_node_get_font
-gsk_text_node_get_glyphs
-gsk_text_node_get_color
-gsk_text_node_has_color_glyphs
-gsk_text_node_get_num_glyphs
-gsk_text_node_get_offset
-<SUBSECTION>
-gsk_blur_node_new
-gsk_blur_node_get_child
-gsk_blur_node_get_radius
-<SUBSECTION>
-gsk_debug_node_new
-gsk_debug_node_get_child
-gsk_debug_node_get_message
-<SUBSECTION>
-gsk_gl_shader_node_new
-gsk_gl_shader_node_get_n_children
-gsk_gl_shader_node_get_child
-gsk_gl_shader_node_get_args
-gsk_gl_shader_node_get_shader
-<SUBSECTION Standard>
-GSK_IS_RENDER_NODE
-GSK_RENDER_NODE
-GSK_TYPE_RENDER_NODE
-GSK_TYPE_BLEND_NODE
-GSK_TYPE_BLUR_NODE
-GSK_TYPE_BORDER_NODE
-GSK_TYPE_CAIRO_NODE
-GSK_TYPE_CLIP_NODE
-GSK_TYPE_COLOR_MATRIX_NODE
-GSK_TYPE_COLOR_NODE
-GSK_TYPE_CONTAINER_NODE
-GSK_TYPE_CONIC_GRADIENT_NODE
-GSK_TYPE_CROSS_FADE_NODE
-GSK_TYPE_DEBUG_NODE
-GSK_TYPE_GL_SHADER_NODE
-GSK_TYPE_INSET_SHADOW_NODE
-GSK_TYPE_LINEAR_GRADIENT_NODE
-GSK_TYPE_OPACITY_NODE
-GSK_TYPE_OUTSET_SHADOW_NODE
-GSK_TYPE_RADIAL_GRADIENT_NODE
-GSK_TYPE_REPEATING_LINEAR_GRADIENT_NODE
-GSK_TYPE_REPEATING_RADIAL_GRADIENT_NODE
-GSK_TYPE_REPEAT_NODE
-GSK_TYPE_ROUNDED_CLIP_NODE
-GSK_TYPE_SHADOW_NODE
-GSK_TYPE_TEXT_NODE
-GSK_TYPE_TEXTURE_NODE
-GSK_TYPE_TRANSFORM_NODE
-GSK_TYPE_GLSHADER_NODE
-GSK_TYPE_RENDER_NODE_TYPE
-GskRenderNodeClass
-gsk_blend_node_get_type
-gsk_blur_node_get_type
-gsk_border_node_get_type
-gsk_broadway_renderer_get_type
-gsk_cairo_node_get_type
-gsk_cairo_renderer_get_type
-gsk_clip_node_get_type
-gsk_color_matrix_node_get_type
-gsk_color_node_get_type
-gsk_conic_gradient_node_get_type
-gsk_container_node_get_type
-gsk_cross_fade_node_get_type
-gsk_debug_node_get_type
-gsk_gl_shader_node_get_type
-gsk_inset_shadow_node_get_type
-gsk_linear_gradient_node_get_type
-gsk_opacity_node_get_type
-gsk_outset_shadow_node_get_type
-gsk_radial_gradient_node_get_type
-gsk_render_node_get_type
-gsk_repeating_linear_gradient_node_get_type
-gsk_repeating_radial_gradient_node_get_type
-gsk_repeat_node_get_type
-gsk_rounded_clip_node_get_type
-gsk_shadow_node_get_type
-gsk_text_node_get_type
-gsk_texture_node_get_type
-gsk_transform_node_get_type
-GSK_TYPE_BLEND_MODE
-<SUBSECTION Standard>
-gsk_serialization_error_quark
-GSK_SERIALIZATION_ERROR
-GSK_TYPE_SERIALIZATION_ERROR
-</SECTION>
-
-<SECTION>
-<FILE>GskRoundedRect</FILE>
-GskCorner
-GskRoundedRect
-GSK_ROUNDED_RECT_INIT
-gsk_rounded_rect_init
-gsk_rounded_rect_init_copy
-gsk_rounded_rect_init_from_rect
-gsk_rounded_rect_normalize
-gsk_rounded_rect_offset
-gsk_rounded_rect_shrink
-gsk_rounded_rect_is_rectilinear
-gsk_rounded_rect_contains_point
-gsk_rounded_rect_contains_rect
-gsk_rounded_rect_intersects_rect
-<SUBSECTION Standard>
-GSK_TYPE_CORNER
-</SECTION>
-
-<SECTION>
-<FILE>GskTransform</FILE>
-GskTransform
-gsk_transform_ref
-gsk_transform_unref
-<SUBSECTION>
-GskTransformCategory
-gsk_transform_get_category
-<SUBSECTION>
-gsk_transform_print
-gsk_transform_to_string
-gsk_transform_parse
-<SUBSECTION>
-gsk_transform_to_matrix
-gsk_transform_to_2d
-gsk_transform_to_affine
-gsk_transform_to_translate
-<SUBSECTION>
-gsk_transform_transform
-gsk_transform_invert
-gsk_transform_matrix
-gsk_transform_translate
-gsk_transform_translate_3d
-gsk_transform_rotate
-gsk_transform_rotate_3d
-gsk_transform_scale
-gsk_transform_scale_3d
-gsk_transform_perspective
-<SUBSECTION>
-gsk_transform_equal
-<SUBSECTION>
-gsk_transform_transform_bounds
-gsk_transform_transform_point
-<SUBSECTION Private>
-GSK_TYPE_TRANSFORM
-GSK_TYPE_TRANSFORM_CATEGORY
-gsk_transform_get_type
-gsk_transform_new
-</SECTION>
-
-<SECTION>
-<FILE>GskGLShader</FILE>
-GskGLShader
-gsk_gl_shader_new_from_bytes
-gsk_gl_shader_new_from_resource
-gsk_gl_shader_compile
-gsk_gl_shader_get_source
-gsk_gl_shader_get_resource
-gsk_gl_shader_get_n_textures
-gsk_gl_shader_get_n_uniforms
-gsk_gl_shader_get_uniform_name
-gsk_gl_shader_find_uniform_by_name
-GskGLUniformType
-gsk_gl_shader_get_uniform_type
-gsk_gl_shader_get_uniform_offset
-gsk_gl_shader_get_args_size
-
-<SUBSECTION Uniform Data>
-gsk_gl_shader_get_arg_float
-gsk_gl_shader_get_arg_int
-gsk_gl_shader_get_arg_uint
-gsk_gl_shader_get_arg_bool
-gsk_gl_shader_get_arg_vec2
-gsk_gl_shader_get_arg_vec3
-gsk_gl_shader_get_arg_vec4
-gsk_gl_shader_format_args_va
-gsk_gl_shader_format_args
-
-<SUBSECTION Shader Args Builder>
-GskShaderArgsBuilder
-
-gsk_shader_args_builder_new
-gsk_shader_args_builder_to_args
-gsk_shader_args_builder_free_to_args
-gsk_shader_args_builder_unref
-gsk_shader_args_builder_ref
-
-gsk_shader_args_builder_set_float
-gsk_shader_args_builder_set_int
-gsk_shader_args_builder_set_uint
-gsk_shader_args_builder_set_bool
-gsk_shader_args_builder_set_vec2
-gsk_shader_args_builder_set_vec3
-gsk_shader_args_builder_set_vec4
-
-<SUBSECTION Private>
-GSK_TYPE_GL_SHADER
-GSK_TYPE_GL_UNIFORM_TYPE
-GSK_TYPE_SHADER_ARGS_BUILDER
-gsk_shader_args_builder_get_type
-</SECTION>
@@ -0,0 +1,46 @@
+[library]
+version = "@version@"
+browse_url = "https://gitlab.gnome.org/GNOME/gtk/"
+repository_url = "https://gitlab.gnome.org/GNOME/gtk.git"
+website_url = "https://www.gtk.org"
+authors = "GTK Development Team"
+logo_url = "gtk-logo.svg"
+license = "GPL-2.1-or-later"
+description = "The GTK toolkit"
+dependencies = [ "GObject-2.0", "Graphene-1.0", "Pango-1.0", "Gdk-4.0" ]
+devhelp = true
+search_index = true
+
+  [dependencies."GObject-2.0"]
+  name = "GObject"
+  description = "The base type system library"
+  docs_url = "https://developer.gnome.org/gobject/stable"
+
+  [dependencies."Graphene-1.0"]
+  name = "Graphene"
+  description = "A thin layer of mathematical types for 3D libraries"
+  docs_url = "https://ebassi.github.io/graphene/docs"
+
+  [dependencies."Pango-1.0"]
+  name = "Pango"
+  description = "Text shaping and rendering"
+  docs_url = "https://developer.gnome.org/pango/stable"
+
+  [dependencies."Gdk-4.0"]
+  name = "GDK"
+  description = "The GTK windowing system abstraction"
+  docs_url = "https://gnome.pages.gitlab.gnome.org/gtk/gdk4/"
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/gtk/-/blob/master/"
+
+[extra]
+content_images = [
+  "gtk-logo.svg",
+]
+urlmap_file = "urlmap.js"
@@ -1,3 +0,0 @@
-gsk_render_node_get_type
-gsk_renderer_get_type
-gsk_gl_shader_get_type
@@ -0,0 +1,138 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="128"
+   height="128"
+   id="svg6843"
+   sodipodi:version="0.32"
+   inkscape:version="0.92.4 5da689c313, 2019-01-14"
+   version="1.0"
+   sodipodi:docname="gtk-logo.svg"
+   inkscape:output_extension="org.inkscape.output.svg.inkscape"
+   inkscape:export-filename="/home/ebassi/Pictures/gtk-logo-256.png"
+   inkscape:export-xdpi="192"
+   inkscape:export-ydpi="192">
+  <defs
+     id="defs6845">
+    <inkscape:perspective
+       sodipodi:type="inkscape:persp3d"
+       inkscape:vp_x="-50 : 600 : 1"
+       inkscape:vp_y="0 : 1000 : 0"
+       inkscape:vp_z="700 : 600 : 1"
+       inkscape:persp3d-origin="300 : 400 : 1"
+       id="perspective13" />
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="2.8284271"
+     inkscape:cx="69.874353"
+     inkscape:cy="64.313526"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     inkscape:document-units="px"
+     inkscape:grid-bbox="true"
+     width="128px"
+     height="128px"
+     showguides="true"
+     inkscape:guide-bbox="true"
+     inkscape:window-width="1920"
+     inkscape:window-height="1016"
+     inkscape:window-x="0"
+     inkscape:window-y="27"
+     inkscape:window-maximized="1">
+    <inkscape:grid
+       type="xygrid"
+       id="grid7947" />
+  </sodipodi:namedview>
+  <metadata
+     id="metadata6848">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title />
+        <dc:date />
+        <dc:creator>
+          <cc:Agent>
+            <dc:title />
+          </cc:Agent>
+        </dc:creator>
+        <dc:rights>
+          <cc:Agent>
+            <dc:title />
+          </cc:Agent>
+        </dc:rights>
+        <dc:publisher>
+          <cc:Agent>
+            <dc:title />
+          </cc:Agent>
+        </dc:publisher>
+        <dc:identifier />
+        <dc:source />
+        <dc:relation />
+        <dc:language />
+        <dc:subject>
+          <rdf:Bag />
+        </dc:subject>
+        <dc:coverage />
+        <dc:description />
+        <dc:contributor>
+          <cc:Agent>
+            <dc:title />
+          </cc:Agent>
+        </dc:contributor>
+        <cc:license
+           rdf:resource="" />
+      </cc:Work>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     id="layer1"
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer">
+    <path
+       sodipodi:nodetypes="ccccc"
+       id="path6976"
+       d="M 20.88413,30.82696 L 53.816977,55.527708 L 107.33282,39.060543 L 70.587303,17.177763 L 20.88413,30.82696 z"
+       style="fill:#729fcf;fill-opacity:1;fill-rule:evenodd;stroke:#ffffff;stroke-width:2.12364459;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;display:inline" />
+    <path
+       id="path6978"
+       d="M 22.94243,82.287118 L 20.88413,30.82696 L 53.816977,55.527708 L 53.816977,111.10486 L 22.94243,82.287118 z"
+       style="fill:#e40000;fill-opacity:1;fill-rule:evenodd;stroke:#ffffff;stroke-width:2.12364459;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;display:inline" />
+    <path
+       id="path6980"
+       d="M 53.816977,111.10486 L 103.21619,90.5207 L 107.33282,39.060543 L 53.816977,55.527708 L 53.816977,111.10486 z"
+       style="fill:#7fe719;fill-opacity:1;fill-rule:evenodd;stroke:#ffffff;stroke-width:2.12364459;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;display:inline" />
+    <path
+       sodipodi:nodetypes="ccc"
+       id="path6982"
+       d="M 23.216626,81.319479 L 70.48573,67.361442 L 103.38422,90.444516"
+       style="opacity:1;fill:none;fill-rule:evenodd;stroke:#ffffff;stroke-width:1.25;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
+    <path
+       sodipodi:nodetypes="cc"
+       id="path6984"
+       d="M 70.434539,17.875593 L 70.434539,66.984877"
+       style="opacity:1;fill:#babdb6;fill-rule:evenodd;stroke:#ffffff;stroke-width:1.25;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
+  </g>
+</svg>
@@ -1,91 +1,24 @@
-private_headers = [
-  'gsk-autocleanup.h',
-
-  'gskcairoblurprivate.h',
-  'gskcairorendererprivate.h',
-  'gskdebugprivate.h',
-  'gskdiffprivate.h',
-  'gskglshaderprivate.h',
-  'gskprivate.h',
-  'gskprofilerprivate.h',
-  'gskrendererprivate.h',
-  'gskrendernodeprivate.h',
-  'gskrendernodeparserprivate.h',
-  'gskroundedrectprivate.h',
-  'gsktransformprivate.h',
-
-  # gsk/gl
-  'glutilsprivate.h',
-  'gskgldriverprivate.h',
-  'gskglglyphcacheprivate.h',
-  'gskgliconcacheprivate.h',
-  'gskglimageprivate.h',
-  'gskglnodesampleprivate.h',
-  'gskglprofilerprivate.h',
-  'gskglrendererprivate.h',
-  'gskglrenderopsprivate.h',
-  'gskglshaderbuilderprivate.h',
-  'gskglshadowcacheprivate.h',
-  'gskgltextureatlasprivate.h',
-  'opbuffer.h',
-  'stb_rect_pack.h',
-
-  # gsk/vulkan
-  'gskvulkanblendmodepipelineprivate.h',
-  'gskvulkanblurpipelineprivate.h',
-  'gskvulkanborderpipelineprivate.h',
-  'gskvulkanboxshadowpipelineprivate.h',
-  'gskvulkanbufferprivate.h',
-  'gskvulkanclipprivate.h',
-  'gskvulkancolorpipelineprivate.h',
-  'gskvulkancolortextpipelineprivate.h',
-  'gskvulkancommandpoolprivate.h',
-  'gskvulkancrossfadepipelineprivate.h',
-  'gskvulkaneffectpipelineprivate.h',
-  'gskvulkanglyphcacheprivate.h',
-  'gskvulkanimageprivate.h',
-  'gskvulkanlineargradientpipelineprivate.h',
-  'gskvulkanmemoryprivate.h',
-  'gskvulkanpipelineprivate.h',
-  'gskvulkanpushconstantsprivate.h',
-  'gskvulkanrendererprivate.h',
-  'gskvulkanrenderpassprivate.h',
-  'gskvulkanrenderprivate.h',
-  'gskvulkanshaderprivate.h',
-  'gskvulkantextpipelineprivate.h',
-  'gskvulkantexturepipelineprivate.h',
-]
-
-images = [
-]
+gsk4_toml = configure_file(input: 'gsk4.toml.in', output: 'gsk4.toml', configuration: toml_conf)

 if get_option('gtk_doc')
-  configure_file(input: 'version.xml.in', output: 'version.xml', configuration: version_conf)
-
-  gnome.gtkdoc('gsk4',
-    mode: 'none',
-    main_xml: 'gsk4-docs.xml',
-    src_dir: [
-      gskinc,
+  custom_target('gsk4-doc',
+    input: [ gsk4_toml, gsk_gir[0] ],
+    output: 'gsk4',
+    command: [
+      gidocgen,
+      'generate',
+      '--quiet',
+      '--add-include-path=@0@'.format(meson.current_build_dir() / '../../../gtk'),
+      '--config=@INPUT0@',
+      '--output-dir=@OUTPUT@',
+      '--no-namespace-dir',
+      '--content-dir=@0@'.format(meson.current_source_dir()),
+      '@INPUT1@',
    ],
-    dependencies: libgtk_dep,
-    gobject_typesfile: join_paths(meson.current_source_dir(), 'gsk4.types'),
-    scan_args: [
-      '--ignore-decorators=_GDK_EXTERN',
-      '--ignore-headers=' + ' '.join(private_headers),
-    ],
-    mkdb_args: [
-      '--ignore-files=' + ' '.join(private_headers),
-    ],
-    fixxref_args: [
-      '--html-dir=@0@'.format(docpath),
-      '--extra-dir=@0@'.format(join_paths(glib_docpath, 'glib')),
-      '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gobject')),
-      '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gio')),
-      '--extra-dir=@0@'.format(cairo_docpath),
-      '--extra-dir=../gdk',
-    ],
-    html_assets: images,
+    depends: [ gdk_gir[0] ],
+    depend_files: [ expand_content_md_files ],
+    build_by_default: true,
    install: true,
+    install_dir: docs_dir,
  )
 endif
@@ -0,0 +1,13 @@
+// SPDX-FileCopyrightText: 2021 GNOME Foundation
+// SPDX-License-Identifier: LGPL-2.1-or-later
+
+// A map between namespaces and base URLs for their online documentation
+baseURLs = [
+    [ 'Gdk', 'https://gnome.pages.gitlab.gnome.org/gtk/gdk4/' ],
+    [ 'GdkWayland', 'https://gnome.pages.gitlab.gnome.org/gtk/gdk4-wayland/' ],
+    [ 'GdkX11', 'https://gnome.pages.gitlab.gnome.org/gtk/gdk4-x11/' ],
+    [ 'Gsk', 'https://gnome.pages.gitlab.gnome.org/gtk/gsk4/' ],
+    [ 'Gtk', 'https://gnome.pages.gitlab.gnome.org/gtk/gtk4/' ],
+    [ 'Pango', 'https://gnome.pages/gitlab.gnome.org/pango/pango/' ],
+    [ 'PangoCairo', 'https://gnome.pages.gitlab.gnome.org/pango/pangocairo/' ],
+]
@@ -1 +0,0 @@
-@GTK_VERSION@
@@ -1,13 +1,14 @@
-# Overview of actions in GTK {#actions-overview}
+Title: Overview of actions in GTK
+Slug: actions

 This chapter describes in detail how GTK uses actions to connect
 activatable UI elements to callbacks. GTK inherits the underlying
-architecture of GAction and GMe:u for describing abstract actions
+architecture of `GAction` and `GMenu` for describing abstract actions
 and menus from the GIO library.

 ## Basics about actions

-A GAction is essentially a way to tell the toolkit about a piece of
+A `GAction` is essentially a way to tell the toolkit about a piece of
 functionality in your program, and to give it a name.

 Actions are purely functional. They do not contain any presentational
@@ -76,7 +77,7 @@ state type, and activating them with a particular parameter value is
 equivalent to changing their state to that value.

 This approach to handling radio buttons is different than many other
-action systems such as GtkAction. With GAction, there is only one action
+action systems such as `GtkAction`. With `GAction`, there is only one action
 for "text-justify" and "left", "center" and "right" are possible states on
 that action. There are not three separate "justify-left", "justify-center"
 and "justify-right" actions.
@@ -96,7 +97,7 @@ Even though toggle actions have a state, they do not have a parameter.
 Therefore, a target value is not needed when referring to them — they
 will always be toggled on activation.

-Most APIs that allow using a GAction (such as GMenuModel and GtkActionable)
+Most APIs that allow using a `GAction` (such as `GMenuModel` and `GtkActionable`)
 allow use of detailed action names. This is a convenient way of specifying
 an action name and an action target with a single string.

@@ -140,7 +141,7 @@ separate state for each instance of the action as well as being able to
 control the enabled state of the action on a per-window basis.

 Actions are added to their relevant scope (application, window or widget)
-either using the GActionMap interface, or by using
+either using the `GActionMap` interface, or by using
 gtk_widget_insert_action_group(). Actions that will be the same for all
 instances of a widget class can be added globally using
 gtk_widget_class_install_action().
@@ -149,7 +150,7 @@ gtk_widget_class_install_action().

 Actions rarely occurs in isolation. It is common to have groups
 of related actions, which are represented by instances of the
-GActionGroup interface.
+`GActionGroup` interface.

 Action maps are a variant of action groups that allow to change
 the name of the action as it is looked up. In GTK, the convention
@@ -160,46 +161,46 @@ or "win." for those with window scope.
 When referring to actions on a GActionMap only the name of the
 action itself is used (ie: "quit", not "app.quit"). The
 "app.quit" form is only used when referring to actions from
-places like a GMenu or GtkActionable widget where the scope
+places like a `GMenu` or `GtkActionable` widget where the scope
 of the action is not already known.

-GtkApplication and GtkApplicationWindow implement the GActionMap
+`GtkApplication` and `GtkApplicationWindow` implement the `GActionMap`
 interface, so you can just add actions directly to them. For
 other widgets, use gtk_widget_insert_action_group() to add
 actions to it.

 If you want to insert several actions at the same time, it is
-typically faster and easier to use GActionEntry.
+typically faster and easier to use `GActionEntry`.

 ## Connecting actions to widgets

-Any widget that implements the GtkActionable interface can
+Any widget that implements the `GtkActionable` interface can
 be connected to an action just by setting the ::action-name
 property. If the action has a parameter, you will also need
-to set the ::action-target property.
-Widgets that implement GtkActionable include GtkSwitch, GtkButton,
-and their respective subclasses.
+to set the ::action-target property. Widgets that implement
+`GtkActionable` include `GtkSwitch`, `GtkButton`, and their
+respective subclasses.

 Another way of obtaining widgets that are connected to actions
-is to create a menu using a GMenu menu model. GMenu provides an
+is to create a menu using a `GMenu` menu model. `GMenu` provides an
 abstract way to describe typical menus: nested groups of items
 where each item can have a label, and icon, and an action.

-A typical use of GMenu inside GTK is to set up an application
+A typical use of `GMenu` inside GTK is to set up an application
 menubar with gtk_application_set_menubar(). Another, maybe more
 common use is to create a popover for a menubutton, using
 gtk_menu_button_set_menu_model().

 Unlike traditional menus, those created from menu models don't
 have keyboard accelerators associated with menu items. Instead,
-GtkApplication offers the gtk_application_set_accels_for_action()
+`GtkApplication` offers the gtk_application_set_accels_for_action()
 API to associate keyboard shortcuts with actions.

 ## Activation

 When a widget with a connected action is activated, GTK finds
 the action to activate by walking up the widget hierarchy,
-looking for a matching action, ending up at the GtkApplication.
+looking for a matching action, ending up at the `GtkApplication`.

 ## Built-in Actions

@@ -209,13 +210,16 @@ you should avoid naming conflicts with them when creating your
 own actions.

 default.activate
- :  Activates the default widget in a context (typically a GtkWindow,
-    GtkDialog or GtkPopover)
+: Activates the default widget in a context (typically a `GtkWindow`,
+  `GtkDialog` or `GtkPopover`)
+
 clipboard.cut, clipboard.copy, clipboard.paste
- :  Clipboard operations on entries, text view and labels, typically
-    used in the context menu
+: Clipboard operations on entries, text view and labels, typically
+  used in the context menu
+
 selection.delete, selection.select-all
- : Selection operations on entries, text view and labels
+: Selection operations on entries, text view and labels
+
 color.select, color.customize:
- : Operate on colors in a #GtkColorChooserWidget. These actions are
-   unusual in that they have the non-trivial parameter type (dddd):
+: Operate on colors in a `GtkColorChooserWidget`. These actions are
+  unusual in that they have the non-trivial parameter type (dddd):
@@ -1,4 +1,7 @@
-# Using GTK with Broadway {#gtk-broadway}
+Title: The Broadway windowing system
+Slug: broadway
+
+## Using GTK with Broadway

 The GDK Broadway backend provides support for displaying GTK
 applications in a web browser, using HTML5 and web sockets. To run
@@ -26,9 +29,9 @@ Start your applications like this:
 GDK_BACKEND=broadway BROADWAY_DISPLAY=:5 gtk4-demo
 ```

-## Broadway-specific environment variables {#broadway-envar}
+## Broadway-specific environment variables

-### BROADWAY_DISPLAY
+### BROADWAY\_DISPLAY

 Specifies the Broadway display number. The default display is 0.
 The display number determines the port to use when connecting
@@ -1,4 +1,5 @@
-# Compiling the GTK Libraries {#gtk-building}
+Title: Compiling the GTK Libraries
+Slug: gtk-building

 ## Building GTK

@@ -75,7 +76,7 @@ PATH="/opt/gtk/bin:$PATH"
 export LD_LIBRARY_PATH PATH
 ```

-## Build types {#build-types}
+## Build types

 Meson has different build types, exposed by the `buildtype`
 configuration option. GTK enables and disables functionality
@@ -111,7 +112,7 @@ linker flags. Note that with the plain build type, you are also
 responsible for controlling the debugging features of GTK with
 `-DG_ENABLE_DEBUG` and `-DG_DISABLE_CAST_CHECKS`.

-## Dependencies {#dependencies}
+## Dependencies

 Before you can compile the GTK widget toolkit, you need to have
 various other tools and libraries installed on your
@@ -179,7 +180,7 @@ Other libraries are maintained separately.
  `XDG_DATA_DIRS` set accordingly at configure time. Otherwise,
  gdk-pixbuf falls back to its built-in mime type detection.

-## Building and testing GTK {#building}
+## Building and testing GTK

 First make sure that you have the necessary external
 dependencies installed: `pkg-config`, Meson, Ninja,
@@ -207,7 +208,7 @@ log that can help you understand the issue you're encountering. If
 all else fails, you can ask for help on the
 [GTK forums](#gtk-resources).

-## Extra Configuration Options {#extra-configuration-options}
+## Extra Configuration Options

 In addition to the normal options provided by Meson, GTK defines various
 arguments that modify what should be built. All of these options are passed
@@ -1,4 +1,5 @@
-# Compiling GTK Applications on UNIX {#gtk-compiling}
+Title: Compiling GTK Applications on UNIX
+Slug: gtk-compiling

 To compile a GTK application, you need to tell the compiler where to
 find the GTK header files and libraries. This is done with the
@@ -1,4 +1,5 @@
-# CSS in GTK {#css}
+Title: CSS in GTK
+Slug: css

 This chapter describes how GTK uses CSS for styling and layout. 
 It is not meant to be an explanation of CSS from first principles,
@@ -1,4 +1,5 @@
-# GTK CSS Properties
+Title: GTK CSS Properties
+Slug: css-properties

 GTK supports CSS properties and shorthands as far as they can be applied
 in the context of widgets, and adds its own properties only when needed.
@@ -14,13 +15,16 @@ spec.
 The following units are supported for basic datatypes:

 Length
- : px, pt, em, ex, rem, pc, in, cm, mm, calc()
+: px, pt, em, ex, rem, pc, in, cm, mm, calc()
+
 Percentage
- : %, calc()
+: %, calc()
+
 Angle
- : deg, grad, turn, calc()
+: deg, grad, turn, calc()
+
 Time
- : s, ms, calc()
+: s, ms, calc()

 Length values with the em or ex units are resolved using the font
 size value, unless they occur in setting the font-size itself, in
@@ -41,13 +45,16 @@ side of an area. In this case, the specified values are interpreted as
 follows:

 4 values:
- : top right bottom left
+: top right bottom left
+
 3 values:
- : top horizontal bottom
+: top horizontal bottom
+
 2 values:
- : vertical horizontal
+: vertical horizontal
+
 1 value:
- : all
+: all

 ## Colors

@@ -1,13 +1,14 @@
-# Overview of the drawing model {#drawing-overview}
+Title: Overview of the drawing model
+Slug: drawing-overview

-This chapter describes the GTK drawing model in detail.  If you
+This chapter describes the GTK drawing model in detail. If you
 are interested in the procedure which GTK follows to draw its
 widgets and windows, you should read this chapter; this will be
-useful to know if you decide to implement your own widgets.  This
+useful to know if you decide to implement your own widgets. This
 chapter will also clarify the reasons behind the ways certain
 things are done in GTK.

-## Windows and events {#drawing-windows}
+## Windows and events

 Applications that use a windowing system generally create
 rectangular regions in the screen called _surfaces_ (GTK is
@@ -27,14 +28,14 @@ windowing system surface. Child widgets such as buttons or
 entries don't have their own surface; they use the surface
 of their toplevel.

-Generally, the drawing cycle begins when GTK receives
-a frame event from the underlying windowing system:  if the
-user drags a window over another one, the windowing system will
-tell the underlying surface that it needs to repaint itself.  The
-drawing cycle can also be initiated when a widget itself decides
-that it needs to update its display.  For example, when the user
-types a character in an entry widget, the entry asks GTK to queue
-a redraw operation for itself.
+Generally, the drawing cycle begins when GTK receives a frame event
+from the underlying windowing system: if the user drags a window
+over another one, the windowing system will tell the underlying
+surface that it needs to repaint itself. The drawing cycle can
+also be initiated when a widget itself decides that it needs to
+update its display. For example, when the user types a character
+in an entry widget, the entry asks GTK to queue a redraw operation
+for itself.

 The windowing system generates frame events for surfaces. The GDK
 interface to the windowing system translates such events into
@@ -46,7 +47,7 @@ need to be repainted in response to such events, and how widgets
 work internally in terms of the resources they use from the
 windowing system.

-## The frame clock {#frameclock}
+## The frame clock

 All GTK applications are mainloop-driven, which means that most
 of the time the app is idle inside a loop that just waits for
@@ -112,7 +113,7 @@ happen at higher levels:
 There are also a lot of implicit triggers of these from the
 CSS layer (which does animations, resizes and repaints as needed).

-## The scene graph {#scene-graph}
+## The scene graph

 The first step in “drawing” a window is that GTK creates
 _render nodes_ for all the widgets in the window. The render
@@ -133,15 +134,15 @@ rendering commands for the drawing API it targets, and arranges
 for the resulting drawing to be associated with the right surface.
 GSK has renderers for OpenGL, Vulkan and cairo.

-## Hierarchical drawing {#hierarchical-drawing}
+## Hierarchical drawing

-During the Paint phase GTK receives a single #GdkSurface::render
-signal on the toplevel surface. The signal handler will create a
-snapshot object (which is a helper for creating a scene graph) and
-call the #GtkWidget::snapshot() vfunc, which will propagate down
-the widget hierarchy. This lets each widget snapshot its content
-at the right place and time, correctly handling things like partial
-transparencies and overlapping widgets.
+During the Paint phase GTK receives a single ::render signal on the
+toplevel surface. The signal handler will create a snapshot object
+(which is a helper for creating a scene graph) and call the
+GtkWidget snapshot() vfunc, which will propagate down the widget
+hierarchy. This lets each widget snapshot its content at the right
+place and time, correctly handling things like partial transparencies
+and overlapping widgets.

 During the snapshotting of each widget, GTK automatically handles
 the CSS rendering according to the CSS box model. It snapshots first
@@ -1,4 +1,5 @@
-# Getting Started with GTK {#gtk-getting-started}
+Title: Getting Started with GTK
+Slug: gtk-getting-started

 GTK is a [widget toolkit](http://en.wikipedia.org/wiki/Widget_toolkit).
 Each user interface created by GTK consists of widgets. This is implemented
@@ -29,7 +30,7 @@ window.

 Create a new file with the following content named `example-0.c`.

-``` {.c source=examples/window-default.c }
+```c
 #include <gtk/gtk.h>

 static void
@@ -63,7 +64,7 @@ main (int    argc,
 You can compile the program above with GCC using:

 ```
-gcc `pkg-config --cflags gtk4` -o example-0 example-0.c `pkg-config --libs gtk4`
+gcc $( pkg-config --cflags gtk4 ) -o example-0 example-0.c $( pkg-config --libs gtk4 )
 ```

 For more information on how to compile a GTK application, please
@@ -77,49 +78,51 @@ Even if GTK installs multiple header files, only the top-level `gtk/gtk.h`
 header can be directly included by third-party code. The compiler will abort
 with an error if any other header is directly included.

-In a GTK application, the purpose of the main() function is to create a
-GtkApplication object and run it. In this example a GtkApplication pointer
-named `app` is declared and then initialized using gtk_application_new().
+In a GTK application, the purpose of the `main()` function is to create a
+[class@Gtk.Application] object and run it. In this example a
+[class@Gtk.Application] pointer named `app` is declared and then initialized
+using `gtk_application_new()`.

-When creating a GtkApplication, you need to pick an application identifier
-(a name) and pass it to gtk_application_new() as parameter. For this example
-`org.gtk.example` is used. For choosing an identifier for your application, see
-[this guide](https://wiki.gnome.org/HowDoI/ChooseApplicationID). Lastly,
-gtk_application_new() takes GApplicationFlags as input for your application,
-if your application would have special needs.
+When creating a [class@Gtk.Application], you need to pick an application
+identifier (a name) and pass it to [ctor@Gtk.Application.new] as parameter. For
+this example `org.gtk.example` is used. For choosing an identifier for your
+application, see [this guide](https://wiki.gnome.org/HowDoI/ChooseApplicationID).
+Lastly, [ctor@Gtk.Application.new] takes `GApplicationFlags` as input
+for your application, if your application would have special needs.

 Next the [activate signal](https://wiki.gnome.org/HowDoI/GtkApplication) is
-connected to the activate() function above the main() function. The `activate`
-signal will be emitted when your application is launched with g_application_run()
-on the line below. The g_application_run() call also takes as arguments the
+connected to the activate() function above the `main()` function. The `activate`
+signal will be emitted when your application is launched with `g_application_run()`
+on the line below. The `g_application_run()` call also takes as arguments the
 command line arguments (the `argc` count and the `argv` string array).
 Your application can override the command line handling, e.g. to open
 files passed on the commandline.

-Within g_application_run() the activate signal is sent and we then proceed
+Within `g_application_run()` the activate signal is sent and we then proceed
 into the activate() function of the application. This is where we construct
 our GTK window, so that a window is shown when the application is launched.
-The call to gtk_application_window_new() will create a new GtkWindow and
-store it inside the `window` pointer. The window will have a frame, a title
-bar, and window controls depending on the platform.
+The call to [ctor@Gtk.ApplicationWindow.new] will create a new
+[class@Gtk.ApplicationWindow] and store it inside the `window` pointer. The
+window will have a frame, a title bar, and window controls depending on the
+platform.

-A window title is set using gtk_window_set_title(). This function takes a
-GtkWindow* pointer and a string as input. As our `window` pointer is a
-GtkWidget pointer, we need to cast it to GtkWindow*. But instead of casting
-`window` via `(GtkWindow*)`, `window` can be cast using the macro
-`GTK_WINDOW()`. `GTK_WINDOW()` will check if the pointer is an instance of
-the GtkWindow class, before casting, and emit a warning if the check fails.
-More information about this convention can be found
-[here](https://developer.gnome.org/gobject/stable/gtype-conventions.html).
+A window title is set using [`method@Gtk.Window.set_title`]. This function
+takes a `GtkWindow` pointer and a string as input. As our `window` pointer
+is a `GtkWidget` pointer, we need to cast it to `GtkWindow`; instead of
+casting `window` via a typical C cast like `(GtkWindow*)`, `window` can be
+cast using the macro `GTK_WINDOW()`. `GTK_WINDOW()` will check if the
+pointer is an instance of the `GtkWindow` class, before casting, and emit a
+warning if the check fails. More information about this convention can be
+found [here](https://developer.gnome.org/gobject/stable/gtype-conventions.html).

-Finally the window size is set using gtk_window_set_default_size()
-and the window is then shown by GTK via gtk_widget_show().
+Finally the window size is set using [`method@Gtk.Window.set_default_size`]
+and the window is then shown by GTK via [method@Gtk.Widget.show].

-When you close the window, by for example pressing the X, the g_application_run()
-call returns with a number which is saved inside an integer variable named
-`status`. Afterwards, the GtkApplication object is freed from memory with
-g_object_unref(). Finally the status integer is returned and the application
-exits.
+When you close the window, by (for example) pressing the X button, the
+`g_application_run()` call returns with a number which is saved inside an
+integer variable named `status`. Afterwards, the `GtkApplication` object is
+freed from memory with `g_object_unref()`. Finally the status integer is
+returned and the application exits.

 While the program is running, GTK is receiving _events_. These are typically
 input events caused by the user interacting with your program, but also things
@@ -138,11 +141,11 @@ this example is called *Hello, World*.

 ![Hello, world](hello-world.png)

-### Hello World in C {#gtk-getting-started-hello-world}
+### Hello World in C

 Create a new file with the following content named `example-1.c`.

-``` {.c source=examples/hello-world.c }
+```c
 #include <gtk/gtk.h>

 static void
@@ -195,43 +198,44 @@ main (int    argc,
 You can compile the program above with GCC using:

 ```
-gcc `pkg-config --cflags gtk4` -o example-1 example-1.c `pkg-config --libs gtk4`
+gcc $( pkg-config --cflags gtk4 ) -o example-1 example-1.c $( pkg-config --libs gtk4 )
 ```

-As seen above, example-1.c builds further upon example-0.c by adding a
-button to our window, with the label "Hello World". Two new GtkWidget
+As seen above, `example-1.c` builds further upon `example-0.c` by adding a
+button to our window, with the label "Hello World". Two new `GtkWidget`
 pointers are declared to accomplish this, `button` and `box`. The box
-variable is created to store a GtkBox, which is GTK's way of controlling
-the size and layout of buttons.
+variable is created to store a [class@Gtk.Box], which is GTK's way of
+controlling the size and layout of buttons.

-The GtkBox is created with gtk_box_new() which takes a GtkOrientation
-enum as parameter. The buttons which this box will contain can either be laid
-out horizontally or vertically. This does not matter in this particular case,
-as we are dealing with only one button. After initializing box with the newly
-created GtkBox, the code adds the box widget to the window widget using
-gtk_window_set_child().
+The `GtkBox` widget is created with [ctor@Gtk.Box.new], which takes a
+[enum@Gtk.Orientation] enumeration value as parameter. The buttons which
+this box will contain can either be laid out horizontally or vertically.
+This does not matter in this particular case, as we are dealing with only
+one button. After initializing box with the newly created `GtkBox`, the code
+adds the box widget to the window widget using [`method@Gtk.Window.set_child`].

 Next the `button` variable is initialized in similar manner.
-gtk_button_new_with_label() is called which returns a GtkButton to be
-stored in `button`. Afterwards `button` is added to our `box`.
+[`ctor@Gtk.Button.new_with_label`] is called which returns a
+[class@Gtk.Button] to be stored in `button`. Afterwards `button` is added to
+our `box`.

-Using g_signal_connect(), the button is connected to a function in our app called
-print_hello(), so that when the button is clicked, GTK will call this function.
-As the print_hello() function does not use any data as input, NULL is passed
-to it. print_hello() calls g_print() with the string "Hello World" which will
+Using `g_signal_connect()`, the button is connected to a function in our app called
+`print_hello()`, so that when the button is clicked, GTK will call this function.
+As the `print_hello()` function does not use any data as input, `NULL` is passed
+to it. `print_hello()` calls `g_print()` with the string "Hello World" which will
 print Hello World in a terminal if the GTK application was started from one.

-After connecting print_hello(), another signal is connected to the "clicked"
-state of the button using g_signal_connect_swapped(). This functions is similar
-to a g_signal_connect() with the difference lying in how the callback function
-is treated. g_signal_connect_swapped() allows you to specify what the callback
+After connecting `print_hello()`, another signal is connected to the "clicked"
+state of the button using `g_signal_connect_swapped()`. This functions is similar
+to a `g_signal_connect()`, with the difference lying in how the callback function
+is treated; `g_signal_connect_swapped()` allows you to specify what the callback
 function should take as parameter by letting you pass it as data. In this case
-the function being called back is gtk_window_destroy() and the `window` pointer
+the function being called back is [method@Gtk.Window.destroy] and the `window` pointer
 is passed to it. This has the effect that when the button is clicked, the whole
-GTK window is destroyed. In contrast if a normal g_signal_connect() were used
-to connect the "clicked" signal with gtk_window_destroy(), then the function
+GTK window is destroyed. In contrast if a normal `g_signal_connect()` were used
+to connect the "clicked" signal with [method@Gtk.Window.destroy], then the function
 would be called on `button` (which would not go well, since the function expects
-a GtkWindow as argument).
+a `GtkWindow` as argument).

 More information about creating buttons can be found
 [here](https://wiki.gnome.org/HowDoI/Buttons).
@@ -255,11 +259,11 @@ arrange several buttons:

 ![Grid packing](grid-packing.png)

-### Packing buttons {#gtk-getting-started-grid-packing}
+### Packing buttons

 Create a new file with the following content named `example-2.c`.

-``` {.c source=examples/grid-packing.c }
+```c
 #include <gtk/gtk.h>

 static void
@@ -334,7 +338,7 @@ main (int    argc,
 You can compile the program above with GCC using:

 ```
-gcc `pkg-config --cflags gtk4` -o example-2 example-2.c `pkg-config --libs gtk4`
+gcc $( pkg-config --cflags gtk4 ) -o example-2 example-2.c $( pkg-config --libs gtk4 )
 ```

 ## Custom Drawing
@@ -342,14 +346,14 @@ gcc `pkg-config --cflags gtk4` -o example-2 example-2.c `pkg-config --libs gtk4`
 Many widgets, like buttons, do all their drawing themselves. You just tell
 them the label you want to see, and they figure out what font to use, draw
 the button outline and focus rectangle, etc. Sometimes, it is necessary to
-do some custom drawing. In that case, a GtkDrawingArea might be the right
+do some custom drawing. In that case, a [class@Gtk.DrawingArea] might be the right
 widget to use. It offers a canvas on which you can draw by setting its
 draw function.

-The contents of a widget often need to be partially or fully redrawn,
-e.g. when another window is moved and uncovers part of the widget, or
-when the window containing it is resized. It is also possible to explicitly
-cause a widget to be redrawn, by calling gtk_widget_queue_draw(). GTK takes
+The contents of a widget often need to be partially or fully redrawn, e.g.
+when another window is moved and uncovers part of the widget, or when the
+window containing it is resized. It is also possible to explicitly cause a
+widget to be redrawn, by calling [`method@Gtk.Widget.queue_draw`]. GTK takes
 care of most of the details by providing a ready-to-use cairo context to the
 draw function.

@@ -359,11 +363,11 @@ demonstrates input event handling with event controllers.

 ![Drawing](drawing.png)

-### Drawing in response to input {#gtk-getting-started-drawing}
+### Drawing in response to input

 Create a new file with the following content named `example-4.c`.

-``` {.c source=examples/drawing.c }
+```c
 #include <gtk/gtk.h>

 /* Surface to store current scribbles */
@@ -556,7 +560,7 @@ main (int    argc,
 You can compile the program above with GCC using:

 ```
-gcc `pkg-config --cflags gtk4` -o example-4 example-4.c `pkg-config --libs gtk4`
+gcc $( pkg-config --cflags gtk4 ) -o example-4 example-4.c $( pkg-config --libs gtk4 )
 ```

 ## Building user interfaces
@@ -567,13 +571,13 @@ cumbersome, and making changes becomes next to impossible.

 Thankfully, GTK supports the separation of user interface
 layout from your business logic, by using UI descriptions in an
-XML format that can be parsed by the GtkBuilder class.</para>
+XML format that can be parsed by the [class@Gtk.Builder] class.

 ### Packing buttons with GtkBuilder

 Create a new file with the following content named `example-3.c`.

-``` {.c source=examples/builder.c }
+```c
 #include <gtk/gtk.h>
 #include <glib/gstdio.h>

@@ -637,7 +641,7 @@ main (int   argc,

 Create a new file with the following content named `builder.ui`.

-``` {.xml source=examples/builder.ui }
+```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <interface>
  <object id="window" class="GtkWindow">
@@ -681,24 +685,24 @@ Create a new file with the following content named `builder.ui`.
 You can compile the program above with GCC using:

 ```
-gcc `pkg-config --cflags gtk4` -o example-3 example-3.c `pkg-config --libs gtk4`
+gcc $( pkg-config --cflags gtk4 ) -o example-3 example-3.c $( pkg-config --libs gtk4 )
 ```

-Note that GtkBuilder can also be used to construct objects that are
+Note that `GtkBuilder` can also be used to construct objects that are
 not widgets, such as tree models, adjustments, etc. That is the reason
-the method we use here is called gtk_builder_get_object() and returns
-a GObject* instead of a GtkWidget*.
+the method we use here is called [`method@Gtk.Builder.get_object`] and returns
+a `GObject` instead of a `GtkWidget`.

-Normally, you would pass a full path to gtk_builder_add_from_file() to
+Normally, you would pass a full path to [`method@Gtk.Builder.add_from_file`] to
 make the execution of your program independent of the current directory.
 A common location to install UI descriptions and similar data is
 `/usr/share/appname`.

 It is also possible to embed the UI description in the source code as a
-string and use gtk_builder_add_from_string() to load it. But keeping the
+string and use [`method@Gtk.Builder.add_from_string`] to load it. But keeping the
 UI description in a separate file has several advantages: It is then possible
 to make minor adjustments to the UI without recompiling your program, and,
-more importantly, graphical UI editors such as [glade](http://glade.gnome.org)
+more importantly, graphical UI editors such as [Glade](http://glade.gnome.org)
 can load the file and allow you to create and modify your UI by point-and-click.

 ## Building applications
@@ -707,41 +711,45 @@ An application consists of a number of files:

 The binary
 : This gets installed in `/usr/bin`.
+
 A desktop file
 : The desktop file provides important information about the application to
   the desktop shell, such as its name, icon, D-Bus name, commandline to launch
   it, etc. It is installed in `/usr/share/applications`.
+
 An icon
 : The icon gets installed in `/usr/share/icons/hicolor/48x48/apps`, where it
-will be found regardless of the current theme.
+   will be found regardless of the current theme.
+
 A settings schema
 : If the application uses GSettings, it will install its schema in
-    `/usr/share/glib-2.0/schemas`, so that tools like dconf-editor can find it.
+   `/usr/share/glib-2.0/schemas`, so that tools like dconf-editor can find it.
+
 Other resources
 : Other files, such as GtkBuilder ui files, are best loaded from
   resources stored in the application binary itself. This eliminates the
   need for most of the files that would traditionally be installed in
   an application-specific location in `/usr/share`.

-GTK includes application support that is built on top of GApplication. In this
+GTK includes application support that is built on top of `GApplication`. In this
 tutorial we'll build a simple application by starting from scratch, adding more
-and more pieces over time. Along the way, we'll learn about GtkApplication,
-templates, resources, application menus, settings, GtkHeaderBar, GtkStack,
-GtkSearchBar, GtkListBox, and more.
+and more pieces over time. Along the way, we'll learn about [class@Gtk.Application],
+templates, resources, application menus, settings, [class@Gtk.HeaderBar], [class@Gtk.Stack],
+[class@Gtk.SearchBar], [class@Gtk.ListBox], and more.

-The full, buildable sources for these examples can be found in the `examples/`
-directory of the GTK source distribution, or
-[online](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples) in the GTK git
-repository. You can build each example separately by using make with the
-`Makefile.example` file. For more information, see the `README` included in the
-examples directory.
+The full, buildable sources for these examples can be found in the
+`examples` directory of the GTK source distribution, or
+[online](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples) in the GTK
+source code repository. You can build each example separately by using make
+with the `Makefile.example` file. For more information, see the `README`
+included in the examples directory.

 ### A trivial application

-When using GtkApplication, the main() function can be very simple. We just call
-g_application_run() and give it an instance of our application class.
+When using `GtkApplication`, the `main()` function can be very simple. We just call
+`g_application_run()` and give it an instance of our application class.

-``` {.c source=examples/application1/main.c }
+```c
 #include <gtk/gtk.h>

 #include "exampleapp.h"
@@ -758,15 +766,15 @@ GtkApplication. Our example does not yet have any interesting functionality.
 All it does is open a window when it is activated without arguments, and open
 the files it is given, if it is started with arguments.

-To handle these two cases, we override the activate() vfunc, which gets called
-when the application is launched without commandline arguments, and the open()
-vfunc, which gets called when the application is launched with commandline
-arguments.
+To handle these two cases, we override the activate() vfunc, which gets
+called when the application is launched without commandline arguments, and
+the `open()` virtual function, which gets called when the application is
+launched with commandline arguments.

-To learn more about GApplication entry points, consult the GIO
-[documentation](https://developer.gnome.org/gio/2.36/GApplication.html#GApplication.description).
+To learn more about `GApplication` entry points, consult the GIO
+[documentation](https://developer.gnome.org/gio/stable/GApplication.html#GApplication.description).

-``` {.c source=examples/application1/exampleapp.c }
+```c
 #include <gtk/gtk.h>

 #include "exampleapp.h"
@@ -833,10 +841,10 @@ example_app_new (void)
 ```

 Another important class that is part of the application support in GTK is
-GtkApplicationWindow. It is typically subclassed as well. Our subclass does
+`GtkApplicationWindow`. It is typically subclassed as well. Our subclass does
 not do anything yet, so we will just get an empty window.

-``` {.c source=examples/application1/examplewin.c }
+```c
 #include <gtk/gtk.h>

 #include "exampleapp.h"
@@ -877,7 +885,7 @@ create an icon and a desktop file.

 ![An icon](exampleapp.png)

-``` { source=examples/application1/org.gtk.exampleapp.desktop }
+```
 [Desktop Entry]
 Type=Application
 Name=Example
@@ -905,7 +913,7 @@ GtkBuilder ui file with our application window class.
 Our simple ui file gives the window a title, and puts a GtkStack
 widget as the main content.

-``` { .xml source=examples/application2/window.ui }
+```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <interface>
  <template class="ExampleAppWindow" parent="GtkApplicationWindow">
@@ -925,14 +933,14 @@ widget as the main content.
 ```

 To make use of this file in our application, we revisit our
-GtkApplicationWindow subclass, and call
-gtk_widget_class_set_template_from_resource() from the class init
+`GtkApplicationWindow` subclass, and call
+`gtk_widget_class_set_template_from_resource()` from the class init
 function to set the ui file as template for this class. We also
-add a call to gtk_widget_init_template() in the instance init
+add a call to `gtk_widget_init_template()` in the instance init
 function to instantiate the template for each instance of our
 class.

-```
+```c
 ...

 static void
@@ -950,6 +958,7 @@ example_app_window_class_init (ExampleAppWindowClass *class)

 ...
 ```
+
 ([full source](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples/application2/exampleappwin.c))

 You may have noticed that we used the `_from_resource()` variant of the function
@@ -958,7 +967,7 @@ that sets a template. Now we need to use
 to include the ui file in the binary. This is commonly done by listing all resources
 in a `.gresource.xml` file, such as this:

-``` { .xml source=examples/application2/exampleapp.gresource.xml }
+```c
 <?xml version="1.0" encoding="UTF-8"?>
 <gresources>
  <gresource prefix="/org/gtk/exampleapp">
@@ -975,8 +984,8 @@ into the application together with the other source files. To do so, we use the
 glib-compile-resources exampleapp.gresource.xml --target=resources.c --generate-source
 ```

-The gnome module of the meson build system provides the
-[gnome.compile_resources()](https://mesonbuild.com/Gnome-module.html#gnomecompile_resources)
+The gnome module of the [Meson build system](https://mesonbuild.com)
+provides the [`gnome.compile_resources()`](https://mesonbuild.com/Gnome-module.html#gnomecompile_resources)
 method for this task.

 Our application now looks like this:
@@ -989,14 +998,14 @@ In this step, we make our application show the content of all the files
 that it is given on the commandline.

 To this end, we add a member to the struct of our application window subclass
-and keep a reference to the GtkStack there. The first member of the struct
+and keep a reference to the `GtkStack` there. The first member of the struct
 should be the parent type from which the class is derived. Here,
-ExampleAppWindow is derived from GtkApplicationWindow. The
-gtk_widget_class_bind_template_child() function arranges things so that after
+`ExampleAppWindow` is derived from `GtkApplicationWindow`. The
+`gtk_widget_class_bind_template_child()` function arranges things so that after
 instantiating the template, the `stack` member of the struct will point to the
 widget of the same name from the template.

-```
+```c
 ...

 struct _ExampleAppWindow
@@ -1020,13 +1029,14 @@ example_app_window_class_init (ExampleAppWindowClass *class)

 ...
 ```
+
 ([full source](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples/application3/exampleappwin.c))

-Now we revisit the example_app_window_open() function that is called for each
+Now we revisit the `example_app_window_open()` function that is called for each
 commandline argument, and construct a GtkTextView that we then add as a page
 to the stack:

-```
+```c
 ...

 void
@@ -1063,14 +1073,16 @@ example_app_window_open (ExampleAppWindow *win,

 ...
 ```
+
 ([full source](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples/application3/exampleappwin.c))

-Lastly, we add a GtkStackSwitcher to the titlebar area in the ui file, and we
+Lastly, we add a [class@Gtk.StackSwitcher] to the titlebar area in the UI file, and we
 tell it to display information about our stack.

 The stack switcher gets all its information it needs to display tabs from
 the stack that it belongs to. Here, we are passing the label to show for
-each file as the last argument to the gtk_stack_add_titled() function.
+each file as the last argument to the [`method@Gtk.Stack.add_titled`]
+function.

 Our application is beginning to take shape:

@@ -1084,7 +1096,7 @@ infrequently used actions that affect the whole application.
 Just like the window template, we specify our menu in a ui file, and add it
 as a resource to our binary.

-``` {.xml source=examples/application4/gears-menu.ui }
+```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <interface>
  <menu id="menu">
@@ -1112,7 +1124,7 @@ of actions to our application.
 Adding the actions is best done in the startup() vfunc, which is guaranteed
 to be called once for each primary application instance:

-```
+```c
 ...

 static void
@@ -1162,11 +1174,12 @@ example_app_class_init (ExampleAppClass *class)

 ...
 ```
+
 ([full source](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples/application4/exampleapp.c))

 Our preferences menu item does not do anything yet, but the Quit menu item
 is fully functional. Note that it can also be activated by the usual Ctrl-Q
-shortcut. The shortcut was added with gtk_application_set_accels_for_action().
+shortcut. The shortcut was added with `gtk_application_set_accels_for_action()`.

 The application menu looks like this:

@@ -1178,10 +1191,10 @@ A typical application will have a some preferences that should be remembered
 from one run to the next. Even for our simple example application, we may
 want to change the font that is used for the content.

-We are going to use GSettings to store our preferences. GSettings requires
+We are going to use `GSettings` to store our preferences. `GSettings` requires
 a schema that describes our settings:

-``` {.xml source=examples/application5/org.gtk.exampleapp.gschema.xml }
+```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <schemalist>
  <schema path="/org/gtk/exampleapp/" id="org.gtk.exampleapp">
@@ -1207,16 +1220,16 @@ a schema that describes our settings:
 Before we can make use of this schema in our application, we need to compile
 it into the binary form that GSettings expects. GIO provides
 [macros](https://developer.gnome.org/gio/2.36/ch31s06.html) to do this in
-autotools-based projects, and the gnome module of the meson build system
-provides the [gnome.compile_schemas()](https://mesonbuild.com/Gnome-module.html#gnomecompile_schemas)
+autotools-based projects, and the gnome module of the Meson build system
+provides the [`gnome.compile_schemas()`](https://mesonbuild.com/Gnome-module.html#gnomecompile_schemas)
 method for this task.

 Next, we need to connect our settings to the widgets that they are supposed
-to control. One convenient way to do this is to use GSettings bind
+to control. One convenient way to do this is to use `GSettings` bind
 functionality to bind settings keys to object properties, as we do here
 for the transition setting.

-```
+```c
 ...

 static void
@@ -1232,6 +1245,7 @@ example_app_window_init (ExampleAppWindow *win)

 ...
 ```
+
 ([full source](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples/application5/exampleappwin.c))

 The code to connect the font setting is a little more involved, since there
@@ -1239,15 +1253,15 @@ is no simple object property that it corresponds to, so we are not going to
 go into that here.

 At this point, the application will already react if you change one of the
-settings, e.g. using the gsettings commandline tool. Of course, we expect
+settings, e.g. using the `gsettings` command line tool. Of course, we expect
 the application to provide a preference dialog for these. So lets do that
-now. Our preference dialog will be a subclass of GtkDialog, and we'll use
-the same techniques that we've already seen: templates, private structs,
-settings bindings.
+now. Our preference dialog will be a subclass of [class@Gtk.Dialog], and
+we'll use the same techniques that we've already seen: templates, private
+structs, settings bindings.

 Lets start with the template.

-``` {.xml source=examples/application6/prefs.ui }
+```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <interface>
  <template class="ExampleAppPrefs" parent="GtkDialog">
@@ -1319,7 +1333,7 @@ Lets start with the template.

 Next comes the dialog subclass.

-``` {.c source=examples/application6/exampleappprefs.c }
+```c
 #include <gtk/gtk.h>

 #include "exampleapp.h"
@@ -1384,7 +1398,7 @@ example_app_prefs_new (ExampleAppWindow *win)
 Now we revisit the `preferences_activated()` function in our application
 class, and make it open a new preference dialog.

-```
+```c
 ...

 static void
@@ -1402,6 +1416,7 @@ preferences_activated (GSimpleAction *action,

 ...
 ```
+
 ([full source](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples/application6/exampleapp.c))

 After all this work, our application can now show a preference dialog
@@ -1412,14 +1427,14 @@ like this:
 ### Adding a search bar

 We continue to flesh out the functionality of our application. For now, we
-add search. GTK supports this with GtkSearchEntry and GtkSearchBar. The
-search bar is a widget that can slide in from the top to present a search
-entry.
+add search. GTK supports this with [class@Gtk.SearchEntry] and
+[class@Gtk.SearchBar]. The search bar is a widget that can slide in from the
+top to present a search entry.

 We add a toggle button to the header bar, which can be used to slide out
 the search bar below the header bar.

-``` {.xml source=examples/application7/window.ui }
+```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <interface>
  <template class="ExampleAppWindow" parent="GtkApplicationWindow">
@@ -1474,7 +1489,7 @@ going to completely go over here. The central piece of the search
 implementation is a signal handler that listens for text changes in
 the search entry.

-```
+```c
 ...

 static void
@@ -1521,6 +1536,7 @@ example_app_window_init (ExampleAppWindow *win)

 ...
 ```
+
 ([full source](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples/application7/exampleappwin.c))

 With the search bar, our application now looks like this:
@@ -1530,9 +1546,9 @@ With the search bar, our application now looks like this:
 ### Adding a side bar

 As another piece of functionality, we are adding a sidebar, which demonstrates
-GtkMenuButton, GtkRevealer and GtkListBox.
+[class@Gtk.MenuButton], [class@Gtk.Revealer] and [class@Gtk.ListBox].

-``` {.xml source=examples/application8/window.ui }
+```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <interface>
  <template class="ExampleAppWindow" parent="GtkApplicationWindow">
@@ -1605,7 +1621,7 @@ The code to populate the sidebar with buttons for the words found in each
 file is a little too involved to go into here. But we'll look at the code
 to add a checkbutton for the new feature to the menu.

-``` {.xml source=examples/application8/gears-menu.ui }
+```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <interface>
  <menu id="menu">
@@ -1630,9 +1646,9 @@ to add a checkbutton for the new feature to the menu.
 ```

 To connect the menuitem to the show-words setting, we use
-a GAction corresponding to the given GSettings key.
+a `GAction` corresponding to the given `GSettings` key.

-```
+```c
 ...

 static void
@@ -1653,6 +1669,7 @@ example_app_window_init (ExampleAppWindow *win)

 ...
 ```
+
 ([full source](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples/application8/exampleappwin.c))

 What our application looks like now:
@@ -1664,7 +1681,7 @@ What our application looks like now:
 Widgets and other objects have many useful properties.

 Here we show some ways to use them in new and flexible ways, by wrapping
-them in actions with GPropertyAction or by binding them with GBinding.
+them in actions with `GPropertyAction` or by binding them with `GBinding`.

 To set this up, we add two labels to the header bar in our window template,
 named `lines_label` and `lines`, and bind them to struct members in the
@@ -1673,7 +1690,7 @@ private struct, as we've seen a couple of times by now.
 We add a new "Lines" menu item to the gears menu, which triggers the
 show-lines action:

-``` {.xml source=examples/application9/gears-menu.ui }
+```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <interface>
  <menu id="menu">
@@ -1710,7 +1727,7 @@ Since we want both labels to appear and disappear together, we bind
 the visible property of the `lines_label` widget to the same property
 of the `lines` widget.

-```
+```c
 ...

 static void
@@ -1729,6 +1746,7 @@ example_app_window_init (ExampleAppWindow *win)

 ...
 ```
+
 ([full source](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples/application9/exampleappwin.c))

 We also need a function that counts the lines of the currently active tab,
@@ -1,199 +0,0 @@
-#!/usr/bin/python3
-#
-# Call pandoc to convert markdown to docbook, then expand gtk-doc
-# abbreviations (|[ ]|, function(), #object, %constant, etc)
-
-import sys
-import re
-import tempfile
-import os.path
-import subprocess
-
-# The following code is taken from gtk-doc
-
-def ExpandAbbreviations(symbol, text):
-    # Hack!
-    # Strip xlink namespace from hrefs since pandoc insists on
-    # inserting them, and namespace setup doesn't transfer across
-    # xi:include.
-    # Yay for XML!
-    text = re.sub('xlink:href', 'href', text)
-
-    # Convert '@param()'
-    text = re.sub(r'(\A|[^\\])\@(\w+((\.|->)\w+)*)\s*\(\)', r'\1<parameter>\2()</parameter>', text)
-
-    # Convert 'function()' or 'macro()'.
-    # if there is abc_*_def() we don't want to make a link to _def()
-    # FIXME: also handle abc(def(....)) : but that would need to be done recursively :/
-    def f1(m):
-        return m.group(1) + MakeXRef(m.group(2), tagify(m.group(2) + "()", "function"))
-    text = re.sub(r'([^\*.\w])(\w+)\s*\(\)', f1, text)
-    # handle #Object.func()
-    text = re.sub(r'(\A|[^\\])#([\w\-:\.]+[\w]+)\s*\(\)', f1, text)
-
-    # Convert '@param', but not '\@param'.
-    text = re.sub(r'(\A|[^\\])\@(\w+((\.|->)\w+)*)', r'\1<parameter>\2</parameter>', text)
-    text = re.sub(r'/\\\@', r'\@', text)
-
-    # Convert '%constant', but not '\%constant'.
-    # Also allow negative numbers, e.g. %-1.
-    def f2(m):
-        return m.group(1) + MakeXRef(m.group(2), tagify(m.group(2), "literal"))
-
-    text = re.sub(r'(\A|[^\\])\%(-?\w+)', f2, text)
-    text = re.sub(r'\\\%', r'\%', text)
-
-    # Convert '#symbol', but not '\#symbol'.
-
-    # Only convert #foo after a space to avoid interfering with
-    # fragment identifiers in urls
-    def f3(m):
-        return m.group(1) + MakeHashXRef(m.group(2), "type")
-
-    text = re.sub(r'(\A|[ ])#([\w\-:\.]+[\w]+)', f3, text)
-    text = re.sub(r'\\#', '#', text)
-
-    return text
-
-# Standard C preprocessor directives, which we ignore for '#' abbreviations.
-PreProcessorDirectives = {
-    'assert', 'define', 'elif', 'else', 'endif', 'error', 'if', 'ifdef', 'ifndef',
-    'include', 'line', 'pragma', 'unassert', 'undef', 'warning'
-}
-
-def MakeHashXRef(symbol, tag):
-    text = symbol
-
-    # Check for things like '#include', '#define', and skip them.
-    if symbol in PreProcessorDirectives:
-        return "#%s" % symbol
-
-    # Get rid of special suffixes ('-struct','-enum').
-    text = re.sub(r'-struct$', '', text)
-    text = re.sub(r'-enum$', '', text)
-
-    # If the symbol is in the form "Object::signal", then change the symbol to
-    # "Object-signal" and use "signal" as the text.
-    if '::' in symbol:
-        o, s = symbol.split('::', 1)
-        symbol = '%s-%s' % (o, s)
-        text = u'“' + s + u'”'
-
-    # If the symbol is in the form "Object:property", then change the symbol to
-    # "Object--property" and use "property" as the text.
-    if ':' in symbol:
-        o, p = symbol.split(':', 1)
-        symbol = '%s--%s' % (o, p)
-        text = u'“' + p + u'”'
-
-    if tag != '':
-        text = tagify(text, tag)
-
-    return MakeXRef(symbol, text)
-
-def MakeXRef(symbol, text=None):
-    """This returns a cross-reference link to the given symbol.
-
-    Though it doesn't try to do this for a few standard C types that it knows
-    won't be in the documentation.
-
-    Args:
-        symbol (str): the symbol to try to create a XRef to.
-        text (str): text to put inside the XRef, defaults to symbol
-
-    Returns:
-        str: a docbook link
-    """
-    symbol = symbol.strip()
-    if not text:
-        text = symbol
-
-        # Get rid of special suffixes ('-struct','-enum').
-        text = re.sub(r'-struct$', '', text)
-        text = re.sub(r'-enum$', '', text)
-
-    if ' ' in symbol:
-        return text
-
-    symbol_id = CreateValidSGMLID(symbol)
-    return "<link linkend=\"%s\">%s</link>" % (symbol_id, text)
-
-def CreateValidSGMLID(xml_id):
-    """Creates a valid SGML 'id' from the given string.
-
-    According to http://www.w3.org/TR/html4/types.html#type-id "ID and NAME
-    tokens must begin with a letter ([A-Za-z]) and may be followed by any number
-    of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons (":"),
-    and periods (".")."
-
-    When creating SGML IDS, we append ":CAPS" to all all-caps identifiers to
-    prevent name clashes (SGML ids are case-insensitive). (It basically never is
-    the case that mixed-case identifiers would collide.)
-
-    Args:
-      id (str): The text to be converted into a valid SGML id.
-
-    Returns:
-      str: The converted id.
-    """
-
-    # Special case, '_' would end up as '' so we use 'gettext-macro' instead.
-    if xml_id == '_':
-        return "gettext-macro"
-
-    xml_id = re.sub(r'[,;]', '', xml_id)
-    xml_id = re.sub(r'[_ ]', '-', xml_id)
-    xml_id = re.sub(r'^-+', '', xml_id)
-    xml_id = xml_id.replace('::', '-')
-    xml_id = xml_id.replace(':', '--')
-
-    # Append ":CAPS" to all all-caps identifiers
-    # FIXME: there are some inconsistencies here, we have index files containing e.g. TRUE--CAPS
-    if xml_id.isupper() and not xml_id.endswith('-CAPS'):
-        xml_id += ':CAPS'
-
-    return xml_id
-
-def tagify(text, elem):
-    # Adds a tag around some text.
-    # e.g tagify("Text", "literal") => "<literal>Text</literal>".
-    return '<' + elem + '>' + text + '</' + elem + '>'
-
-# End of gtk-doc excerpts
-
-MarkdownExtensions = {
-  '-auto_identifiers', # we use explicit identifiers where needed
-  '+header_attributes', # for explicit identifiers
-  '+blank_before_header', # helps with gtk-doc #Object abbreviations
-  '+compact_definition_lists', # to replace <variablelist>
-  '+pipe_tables',
-  '+backtick_code_blocks', # to replace |[ ]|
-  '+fenced_code_attributes', # to add language annotations
-  '-raw_html', # to escape literal tags like <child> in input
-  '+startnum', # to have interrupted lists in the q&a part
-}
-
-def ConvertToDocbook(infile, outfile):
-    basename = os.path.basename(infile)
-    if basename.startswith('section'):
-        division='section'
-    else:
-        division='chapter'
-    input_format = "markdown" + "".join(MarkdownExtensions)
-    output_format = "docbook4"
-    subprocess.check_call(["pandoc", infile, "-o", outfile,
-                           "--from=" + input_format,
-                           "--to=" + output_format,
-                           "--top-level-division=" + division])
-
-def ExpandGtkDocAbbreviations(infile, outfile):
-    contents = open(infile, 'r', encoding='utf-8').read()
-    with open(outfile, 'w', encoding='utf-8') as out:
-        out.write(ExpandAbbreviations("file", contents))
-
-
-if __name__ == '__main__':
-    tmp = tempfile.mktemp()
-    ConvertToDocbook(sys.argv[1], tmp)
-    ExpandGtkDocAbbreviations(tmp, sys.argv[2])
-    os.remove(tmp)
@@ -1,496 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
-<!ENTITY version SYSTEM "version.xml">
-<!ENTITY pi "&#960;">
-<!ENTITY solidus "&#8260;">
-]>
-<book xmlns="http://docbook.org/ns/docbook" id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
-  <bookinfo>
-    <title>GTK 4 Reference Manual</title>
-    <releaseinfo>
-      This document is for the GTK 4 library, version &version;.
-      The latest versions can be found online at
-      <ulink role="online-location" url="https://developer.gnome.org/gtk4/">https://developer.gnome.org/gtk4/</ulink>.
-      If you are looking for the older GTK 3 series of libraries,
-      see <ulink role="online-location" url="https://developer.gnome.org/gtk3/">https://developer.gnome.org/gtk3/</ulink>.
-    </releaseinfo>
-  </bookinfo>
-
-  <part id="gtk">
-    <title>Introduction</title>
-    <xi:include href="overview.xml"/>
-    <xi:include href="getting_started.xml"/>
-    <xi:include href="resources.xml" />
-    <xi:include href="question_index.xml" />
-  </part>
-
-  <part id="concepts">
-    <title>GTK Concepts</title>
-    <xi:include href="drawing-model.xml" />
-    <xi:include href="input-handling.xml" />
-    <xi:include href="actions.xml" />
-  </part>
-
-  <part id="gtkobjects">
-    <title>GTK Widgets and Objects</title>
-
-    <chapter>
-      <title>Object Hierarchy</title>
-      <xi:include href="xml/tree_index.sgml" />
-    </chapter>
-
-    <chapter>
-      <title>Widget Gallery</title>
-      <xi:include href="visual_index.xml" />
-    </chapter>
-
-    <chapter id="Lists">
-      <title>GListModel support</title>
-      <xi:include href="xml/gtkbitset.xml" />
-      <xi:include href="xml/gtkexpression.xml" />
-      <xi:include href="xml/gtkfilterlistmodel.xml" />
-      <section>
-        <xi:include href="xml/gtkfilter.xml" />
-        <xi:include href="xml/gtkcustomfilter.xml" />
-        <xi:include href="xml/gtkmultifilter.xml" />
-        <xi:include href="xml/gtkboolfilter.xml" />
-        <xi:include href="xml/gtkstringfilter.xml" />
-        <xi:include href="xml/gtkfilefilter.xml" />
-      </section>
-      <xi:include href="xml/gtkflattenlistmodel.xml" />
-      <xi:include href="xml/gtkmaplistmodel.xml" />
-      <xi:include href="xml/gtkslicelistmodel.xml" />
-      <xi:include href="xml/gtksortlistmodel.xml" />
-      <section>
-        <xi:include href="xml/gtksorter.xml" />
-        <xi:include href="xml/gtkcustomsorter.xml" />
-        <xi:include href="xml/gtkmultisorter.xml" />
-        <xi:include href="xml/gtkstringsorter.xml" />
-        <xi:include href="xml/gtknumericsorter.xml" />
-      </section>
-      <xi:include href="xml/gtkselectionmodel.xml" />
-      <section>
-        <xi:include href="xml/gtknoselection.xml" />
-        <xi:include href="xml/gtksingleselection.xml" />
-        <xi:include href="xml/gtkmultiselection.xml" />
-      </section>
-      <xi:include href="xml/gtkselectionfiltermodel.xml" />
-      <xi:include href="xml/gtkbookmarklist.xml" />
-      <xi:include href="xml/gtkdirectorylist.xml" />
-      <xi:include href="xml/gtkstringlist.xml" />
-    </chapter>
-
-    <chapter id="ListContainers">
-      <title>List-based Widgets</title>
-      <xi:include href="section-list-widget.xml"/>
-      <xi:include href="xml/gtklistitem.xml" />
-      <xi:include href="xml/gtklistitemfactory.xml" />
-      <section>
-        <xi:include href="xml/gtksignallistitemfactory.xml" />
-        <xi:include href="xml/gtkbuilderlistitemfactory.xml" />
-      </section>
-      <xi:include href="xml/gtklistview.xml" />
-      <xi:include href="xml/gtkgridview.xml" />
-      <xi:include href="xml/gtkcolumnview.xml" />
-      <section>
-        <xi:include href="xml/gtkcolumnviewcolumn.xml" />
-      </section>
-      <xi:include href="xml/gtkdropdown.xml" />
-    </chapter>
-
-    <chapter id="Trees">
-      <title>Tree support</title>
-      <xi:include href="xml/gtktreelistmodel.xml" />
-      <section>
-        <xi:include href="xml/gtktreelistrow.xml" />
-      </section>
-      <xi:include href="xml/gtktreelistrowsorter.xml" />
-      <xi:include href="xml/gtktreeexpander.xml" />
-    </chapter>
-
-    <chapter id="Application">
-      <title>Application support</title>
-      <xi:include href="xml/gtkapplication.xml" />
-      <xi:include href="xml/gtkapplicationwindow.xml" />
-      <xi:include href="xml/gtkactionable.xml" />
-    </chapter>
-
-    <chapter id="Builder">
-      <title>Interface builder</title>
-      <xi:include href="xml/gtkbuilder.xml" />
-      <xi:include href="xml/gtkbuildable.xml" />
-      <xi:include href="xml/gtkbuilderscope.xml" />
-    </chapter>
-
-    <chapter id="WindowWidgets">
-      <title>Windows</title>
-      <xi:include href="xml/gtkroot.xml" />
-      <xi:include href="xml/gtknative.xml" />
-      <xi:include href="xml/gtkwindow.xml" />
-      <xi:include href="xml/gtkdialog.xml" />
-      <xi:include href="xml/gtkmessagedialog.xml" />
-      <xi:include href="xml/gtkaboutdialog.xml" />
-      <xi:include href="xml/gtkassistant.xml" />
-      <xi:include href="xml/gtkwindowgroup.xml" />
-      <xi:include href="xml/gtknativedialog.xml" />
-    </chapter>
-
-    <chapter id="LayoutContainers">
-      <title>Layout Containers</title>
-      <xi:include href="xml/gtkbox.xml" />
-      <xi:include href="xml/gtkcenterbox.xml" />
-      <xi:include href="xml/gtkgrid.xml" />
-      <xi:include href="xml/gtkrevealer.xml" />
-      <xi:include href="xml/gtklistbox.xml" />
-      <xi:include href="xml/gtkflowbox.xml" />
-      <xi:include href="xml/gtkstack.xml" />
-      <xi:include href="xml/gtkstackswitcher.xml" />
-      <xi:include href="xml/gtkstacksidebar.xml" />
-      <xi:include href="xml/gtkactionbar.xml" />
-      <xi:include href="xml/gtkheaderbar.xml" />
-      <xi:include href="xml/gtkoverlay.xml" />
-      <xi:include href="xml/gtkpaned.xml" />
-      <xi:include href="xml/gtknotebook.xml" />
-      <xi:include href="xml/gtkexpander.xml" />
-      <xi:include href="xml/gtkorientable.xml" />
-      <xi:include href="xml/gtkaspectframe.xml" />
-      <xi:include href="xml/gtkfixed.xml" />
-    </chapter>
-
-    <chapter id="LayoutManagers">
-      <title>Layout Managers</title>
-      <xi:include href="xml/gtklayoutmanager.xml" />
-      <xi:include href="xml/gtklayoutchild.xml" />
-      <xi:include href="xml/gtkbinlayout.xml" />
-      <xi:include href="xml/gtkboxlayout.xml" />
-      <xi:include href="xml/gtkcenterlayout.xml" />
-      <xi:include href="xml/gtkfixedlayout.xml" />
-      <xi:include href="xml/gtkgridlayout.xml" />
-      <xi:include href="xml/gtkoverlaylayout.xml" />
-      <xi:include href="xml/gtkcustomlayout.xml" />
-      <xi:include href="xml/gtkconstraintlayout.xml" />
-      <xi:include href="xml/gtkconstraint.xml" />
-      <xi:include href="xml/gtkconstraintguide.xml" />
-    </chapter>
-
-    <chapter id="DisplayWidgets">
-      <title>Display Widgets</title>
-      <xi:include href="xml/gtklabel.xml" />
-      <xi:include href="xml/gtkimage.xml" />
-      <xi:include href="xml/gtkpicture.xml" />
-      <xi:include href="xml/gtkspinner.xml" />
-      <xi:include href="xml/gtkinfobar.xml" />
-      <xi:include href="xml/gtkprogressbar.xml" />
-      <xi:include href="xml/gtklevelbar.xml" />
-      <xi:include href="xml/gtkstatusbar.xml" />
-      <xi:include href="xml/gtkcalendar.xml" />
-    </chapter>
-
-    <chapter id="MediaSupport">
-      <title>Media Support</title>
-      <xi:include href="xml/gtkvideo.xml" />
-      <xi:include href="xml/gtkmediacontrols.xml" />
-      <xi:include href="xml/gtkmediastream.xml" />
-      <xi:include href="xml/gtkmediafile.xml" />
-    </chapter>
-
-    <chapter id="ButtonWidgets">
-      <title>Buttons and Toggles</title>
-      <xi:include href="xml/gtkbutton.xml" />
-      <xi:include href="xml/gtkcheckbutton.xml" />
-      <xi:include href="xml/gtktogglebutton.xml" />
-      <xi:include href="xml/gtklinkbutton.xml" />
-      <xi:include href="xml/gtkmenubutton.xml" />
-      <xi:include href="xml/gtkswitch.xml" />
-      <xi:include href="xml/gtkscalebutton.xml" />
-      <xi:include href="xml/gtkvolumebutton.xml" />
-      <xi:include href="xml/gtklockbutton.xml" />
-    </chapter>
-
-    <chapter id="NumericEntry">
-      <title>Numeric and Text Data Entry</title>
-      <xi:include href="xml/gtkeditable.xml" />
-      <xi:include href="xml/gtkentrybuffer.xml" />
-      <xi:include href="xml/gtktext.xml" />
-      <xi:include href="xml/gtkentry.xml" />
-      <xi:include href="xml/gtkentrycompletion.xml" />
-      <xi:include href="xml/gtkpasswordentry.xml" />
-      <xi:include href="xml/gtkscale.xml" />
-      <xi:include href="xml/gtkspinbutton.xml" />
-      <xi:include href="xml/gtksearchentry.xml" />
-      <xi:include href="xml/gtksearchbar.xml" />
-      <xi:include href="xml/gtkeditablelabel.xml" />
-    </chapter>
-
-    <chapter id="TextWidgetObjects">
-      <title>Multiline Text Editor</title>
-      <xi:include href="section-text-widget.xml" />
-      <xi:include href="xml/gtktextiter.xml" />
-      <xi:include href="xml/gtktextmark.xml" />
-      <xi:include href="xml/gtktextbuffer.xml" />
-      <xi:include href="xml/gtktexttag.xml" />
-      <xi:include href="xml/gtktexttagtable.xml" />
-      <xi:include href="xml/gtktextview.xml" />
-    </chapter>
-
-    <chapter id="TreeWidgetObjects">
-      <title>Tree, List and Icon Grid Widgets</title>
-      <xi:include href="section-tree-widget.xml" />
-      <xi:include href="xml/gtktreemodel.xml" />
-      <xi:include href="xml/gtktreeselection.xml" />
-      <xi:include href="xml/gtktreeviewcolumn.xml" />
-      <xi:include href="xml/gtktreeview.xml" />
-      <xi:include href="xml/gtktreednd.xml" />
-      <xi:include href="xml/gtkcellview.xml" />
-      <xi:include href="xml/gtkiconview.xml" />
-      <xi:include href="xml/gtktreesortable.xml" />
-      <xi:include href="xml/gtktreemodelsort.xml" />
-      <xi:include href="xml/gtktreemodelfilter.xml" />
-      <xi:include href="xml/gtkcelllayout.xml" />
-      <xi:include href="xml/gtkcellarea.xml" />
-      <xi:include href="xml/gtkcellareabox.xml" />
-      <xi:include href="xml/gtkcellareacontext.xml" />
-      <xi:include href="xml/gtkcellrenderer.xml" />
-      <xi:include href="xml/gtkcelleditable.xml" />
-      <xi:include href="xml/gtkcellrendereraccel.xml" />
-      <xi:include href="xml/gtkcellrenderercombo.xml" />
-      <xi:include href="xml/gtkcellrendererpixbuf.xml" />
-      <xi:include href="xml/gtkcellrendererprogress.xml" />
-      <xi:include href="xml/gtkcellrendererspin.xml" />
-      <xi:include href="xml/gtkcellrenderertext.xml" />
-      <xi:include href="xml/gtkcellrenderertoggle.xml" />
-      <xi:include href="xml/gtkcellrendererspinner.xml" />
-      <xi:include href="xml/gtkliststore.xml" />
-      <xi:include href="xml/gtktreestore.xml" />
-    </chapter>
-
-    <chapter id="MenusAndCombos">
-      <title>Menus, Combo Box</title>
-      <xi:include href="xml/gtkcombobox.xml" />
-      <xi:include href="xml/gtkcomboboxtext.xml" />
-      <xi:include href="xml/gtkpopover.xml" />
-      <xi:include href="xml/gtkpopovermenu.xml" />
-      <xi:include href="xml/gtkpopovermenubar.xml" />
-      <xi:include href="xml/gtkdropdown.xml" />
-    </chapter>
-
-    <chapter id="SelectorWidgets">
-      <title>Selector Widgets and Dialogs</title>
-      <xi:include href="xml/gtkcolorchooser.xml" />
-      <xi:include href="xml/gtkcolorbutton.xml" />
-      <xi:include href="xml/gtkcolorchooserwidget.xml" />
-      <xi:include href="xml/gtkcolorchooserdialog.xml" />
-      <xi:include href="xml/gtkfilechooser.xml" />
-      <xi:include href="xml/gtkfilechoosernative.xml" />
-      <xi:include href="xml/gtkfilechooserdialog.xml" />
-      <xi:include href="xml/gtkfilechooserwidget.xml" />
-      <xi:include href="xml/gtkfontchooser.xml" />
-      <xi:include href="xml/gtkfontbutton.xml" />
-      <xi:include href="xml/gtkfontchooserwidget.xml" />
-      <xi:include href="xml/gtkfontchooserdialog.xml" />
-      <xi:include href="xml/gtkemojichooser.xml" />
-    </chapter>
-
-    <chapter id="DrawingWidgets">
-      <title>Widgets for custom drawing</title>
-      <xi:include href="xml/gtkdrawingarea.xml" />
-      <xi:include href="xml/gtkglarea.xml" />
-    </chapter>
-
-    <chapter id="Ornaments">
-      <title>Ornaments</title>
-      <xi:include href="xml/gtkframe.xml" />
-      <xi:include href="xml/gtkseparator.xml" />
-    </chapter>
-
-    <chapter id="ScrollingWidgets">
-      <title>Scrolling</title>
-      <xi:include href="xml/gtkscrollbar.xml" />
-      <xi:include href="xml/gtkscrolledwindow.xml" />
-      <xi:include href="xml/gtkscrollable.xml" />
-      <xi:include href="xml/gtkviewport.xml" />
-    </chapter>
-
-    <chapter id="Printing">
-      <title>Printing</title>
-      <xi:include href="xml/gtkprintoperation.xml" />
-      <xi:include href="xml/gtkprintcontext.xml" />
-      <xi:include href="xml/gtkprintsettings.xml" />
-      <xi:include href="xml/gtkpagesetup.xml" />
-      <xi:include href="xml/gtkpapersize.xml" />
-      <xi:include href="xml/gtkprinter.xml" />
-      <xi:include href="xml/gtkprintjob.xml" />
-      <xi:include href="xml/gtkprintunixdialog.xml" />
-      <xi:include href="xml/gtkpagesetupunixdialog.xml" />
-    </chapter>
-
-    <chapter id="ShortcutsOverview">
-      <title>Shortcuts Overview</title>
-      <xi:include href="xml/gtkshortcutswindow.xml" />
-      <xi:include href="xml/gtkshortcutssection.xml" />
-      <xi:include href="xml/gtkshortcutsgroup.xml" />
-      <xi:include href="xml/gtkshortcutsshortcut.xml" />
-      <xi:include href="xml/gtkshortcutlabel.xml" />
-    </chapter>
-
-    <chapter id="Accessibility">
-      <title>Accessibility</title>
-      <xi:include href="section-accessibility.xml"/>
-      <xi:include href="xml/gtkaccessible.xml" />
-      <xi:include href="xml/gtkatcontext.xml" />
-    </chapter>
-
-    <chapter id="MiscObjects">
-      <title>Miscellaneous</title>
-      <xi:include href="xml/gtkadjustment.xml" />
-      <xi:include href="xml/gtkimcontextsimple.xml" />
-      <xi:include href="xml/gtkimmulticontext.xml" />
-      <xi:include href="xml/gtksizegroup.xml" />
-      <xi:include href="xml/gtksnapshot.xml" />
-      <xi:include href="xml/gtktooltip.xml" />
-      <xi:include href="xml/gtkwidgetpaintable.xml" />
-      <xi:include href="xml/gtkwindowcontrols.xml" />
-      <xi:include href="xml/gtkwindowhandle.xml" />
-    </chapter>
-
-    <chapter id="AbstractObjects">
-      <title>Abstract Base Classes</title>
-      <xi:include href="xml/gtkwidget.xml" />
-      <xi:include href="xml/gtkrange.xml" />
-      <xi:include href="xml/gtkimcontext.xml" />
-      <xi:include href="xml/gtknativedialog.xml" />
-      <xi:include href="xml/gtkaccessible.xml" />
-    </chapter>
-
-    <chapter id="RecentDocuments">
-      <title>Recently Used Documents</title>
-      <xi:include href="xml/gtkrecentmanager.xml" />
-    </chapter>
-
-    <chapter id="ApplicationChoosing">
-      <title>Choosing from installed applications</title>
-      <xi:include href="xml/gtkappchooser.xml" />
-      <xi:include href="xml/gtkappchooserbutton.xml" />
-      <xi:include href="xml/gtkappchooserdialog.xml" />
-      <xi:include href="xml/gtkappchooserwidget.xml" />
-    </chapter>
-
-    <chapter id="Gestures">
-      <title>Gestures and event handling</title>
-      <xi:include href="xml/gtkeventcontroller.xml" />
-      <xi:include href="xml/gtkeventcontrollerkey.xml" />
-      <xi:include href="xml/gtkeventcontrollerfocus.xml" />
-      <xi:include href="xml/gtkeventcontrollerlegacy.xml" />
-      <xi:include href="xml/gtkeventcontrollerscroll.xml" />
-      <xi:include href="xml/gtkeventcontrollermotion.xml" />
-      <xi:include href="xml/gtkgesture.xml" />
-      <xi:include href="xml/gtkgesturesingle.xml" />
-      <xi:include href="xml/gtkgesturedrag.xml" />
-      <xi:include href="xml/gtkgesturelongpress.xml" />
-      <xi:include href="xml/gtkgestureclick.xml" />
-      <xi:include href="xml/gtkgesturepan.xml" />
-      <xi:include href="xml/gtkgestureswipe.xml" />
-      <xi:include href="xml/gtkgesturerotate.xml" />
-      <xi:include href="xml/gtkgesturezoom.xml" />
-      <xi:include href="xml/gtkgesturestylus.xml" />
-      <xi:include href="xml/gtkpadcontroller.xml" />
-      <xi:include href="xml/gtkshortcutcontroller.xml" />
-    </chapter>
-
-    <chapter>
-      <title>Keyboard shortcuts</title>
-      <xi:include href="xml/gtkaccelgroup.xml" />
-      <xi:include href="xml/gtkshortcut.xml" />
-      <xi:include href="xml/gtkshortcuttrigger.xml" />
-      <xi:include href="xml/gtkshortcutaction.xml" />
-      <xi:include href="xml/gtkshortcutmanager.xml" />
-    </chapter>
-
-    <chapter>
-      <title>Data exchange, clipboards and Drag-and-Drop</title>
-      <xi:include href="xml/gtkdragsource.xml"/>
-      <xi:include href="xml/gtkdragicon.xml"/>
-      <xi:include href="xml/gtkdroptarget.xml"/>
-      <xi:include href="xml/gtkdroptargetasync.xml"/>
-      <xi:include href="xml/gtkdropcontrollermotion.xml"/>
-    </chapter>
-
-  </part>
-
-  <part  id="gtkbase">
-    <title>GTK Core Reference</title>
-    <xi:include href="xml/gtkmain.xml" />
-    <xi:include href="xml/gtkfeatures.xml" />
-    <xi:include href="xml/gtksettings.xml" />
-    <xi:include href="xml/gtkenums.xml" />
-    <xi:include href="xml/gtktesting.xml" />
-    <xi:include href="xml/filesystem.xml" />
-  </part>
-
-  <part id="theming">
-    <title>Theming in GTK</title>
-    <xi:include href="css-overview.xml" />
-    <xi:include href="css-properties.xml" />
-    <xi:include href="xml/gtkstylecontext.xml" />
-    <xi:include href="xml/gtkcssprovider.xml" />
-    <xi:include href="xml/gtkstyleprovider.xml" />
-    <xi:include href="xml/gtkicontheme.xml" />
-  </part>
-
-  <part id="migrating">
-    <title>Migrating from Previous Versions of GTK</title>
-
-    <partintro>
-      <para>
-        This part describes what you need to change in programs use
-        older versions of GTK so that they can use the new features.
-        It also mentions how to convert applications using widgets
-        found in the libgnomeui library to use their counterparts
-        in GTK.
-      </para>
-    </partintro>
-
-    <xi:include href="migrating-2to4.xml" />
-    <xi:include href="migrating-3to4.xml" />
-  </part>
-
-  <part>
-    <title>GTK Tools</title>
-    <xi:include href="gtk4-demo.xml" />
-    <xi:include href="gtk4-demo-application.xml" />
-    <xi:include href="gtk4-widget-factory.xml" />
-    <xi:include href="gtk4-icon-browser.xml" />
-    <xi:include href="gtk4-update-icon-cache.xml" />
-    <xi:include href="gtk4-encode-symbolic-svg.xml" />
-    <xi:include href="gtk4-builder-tool.xml" />
-    <xi:include href="gtk4-launch.xml" />
-    <xi:include href="gtk4-query-settings.xml" />
-    <xi:include href="gtk4-broadwayd.xml" />
-  </part>
-
-  <part id="platform-support">
-    <title>GTK Platform Support</title>
-    <xi:include href="building.xml" />
-    <xi:include href="compiling.xml" />
-    <xi:include href="running.xml" />
-    <xi:include href="x11.xml" />
-    <xi:include href="windows.xml" />
-    <xi:include href="osx.xml" />
-    <xi:include href="broadway.xml" />
-    <xi:include href="wayland.xml" />
-  </part>
-
-  <index id="api-index-full">
-    <title>Index of all symbols</title>
-    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-deprecated" role="deprecated">
-    <title>Index of deprecated symbols</title>
-    <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
-  </index>
-
-  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
-
-</book>
@@ -0,0 +1,235 @@
+[library]
+version = "@version@"
+browse_url = "https://gitlab.gnome.org/GNOME/gtk/"
+repository_url = "https://gitlab.gnome.org/GNOME/gtk.git"
+website_url = "https://www.gtk.org"
+authors = "GTK Development Team"
+logo_url = "gtk-logo.svg"
+license = "GPL-2.1-or-later"
+description = "The GTK toolkit"
+dependencies = [ "GObject-2.0", "Graphene-1.0", "Pango-1.0", "Gdk-4.0", "Gsk-4.0" ]
+devhelp = true
+search_index = true
+
+  [dependencies."GObject-2.0"]
+  name = "GObject"
+  description = "The base type system library"
+  docs_url = "https://developer.gnome.org/gobject/stable"
+
+  [dependencies."Graphene-1.0"]
+  name = "Graphene"
+  description = "A thin layer of mathematical types for 3D libraries"
+  docs_url = "https://ebassi.github.io/graphene/docs"
+
+  [dependencies."Pango-1.0"]
+  name = "Pango"
+  description = "Text shaping and rendering"
+  docs_url = "https://developer.gnome.org/pango/stable"
+
+  [dependencies."Gdk-4.0"]
+  name = "GDK"
+  description = "The GTK windowing system abstraction"
+  docs_url = "https://gnome.pages.gitlab.gnome.org/gtk/gdk4/"
+
+  [dependencies."Gsk-4.0"]
+  name = "GSK"
+  description = "The GTK rendering abstraction"
+  docs_url = "https://gnome.pages.gitlab.gnome.org/gtk/gsk4/"
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/gtk/-/blob/master/"
+
+[extra]
+# The same order will be used when generating the index
+content_files = [
+  "overview.md",
+  "getting_started.md",
+  "building.md",
+  "compiling.md",
+  "running.md",
+  "question_index.md",
+  "resources.md",
+  "initialization.md",
+  "actions.md",
+  "input-handling.md",
+  "drawing-model.md",
+  "css-overview.md",
+  "css-properties.md",
+  "section-accessibility.md",
+  "section-list-widget.md",
+  "section-text-widget.md",
+  "section-tree-widget.md",
+  "migrating-2to4.md",
+  "migrating-3to4.md",
+  "broadway.md",
+  "osx.md",
+  "wayland.md",
+  "windows.md",
+  "x11.md",
+  "visual_index.md",
+]
+content_images = [
+  "images/aboutdialog.png",
+  "images/action-bar.png",
+  "images/appchooserbutton.png",
+  "images/appchooserdialog.png",
+  "images/arrows.png",
+  "images/assistant.png",
+  "images/background.png",
+  "images/bloatpad-gnome.png",
+  "images/bloatpad-osx.png",
+  "images/bloatpad-xfce.png",
+  "images/border1.png",
+  "images/border2.png",
+  "images/border3.png",
+  "images/box.png",
+  "images/box-expand.png",
+  "images/box-packing.png",
+  "images/builder-shortcuts.png",
+  "images/button.png",
+  "images/calendar.png",
+  "images/capture-bubble.png",
+  "images/centerbox.png",
+  "images/check-button.png",
+  "images/checks.png",
+  "images/clocks-shortcuts.png",
+  "images/color-button.png",
+  "images/colorchooser.png",
+  "images/combo-box-entry.png",
+  "images/combo-box.png",
+  "images/combo-box-text.png",
+  "images/dialog.png",
+  "images/down-center.png",
+  "images/down-end.png",
+  "images/down-start.png",
+  "images/drop-down.png",
+  "images/drawing.png",
+  "images/drawingarea.png",
+  "images/ease-in-out.png",
+  "images/ease-in.png",
+  "images/ease-out.png",
+  "images/ease.png",
+  "images/editable-label.png",
+  "images/emojichooser.png",
+  "images/entry.png",
+  "images/exampleapp.png",
+  "images/expanders.png",
+  "images/expander.png",
+  "images/extensions.png",
+  "images/figure-hierarchical-drawing.png",
+  "images/figure-windowed-label.png",
+  "images/file-button.png",
+  "images/filechooser.png",
+  "images/flow-box.png",
+  "images/focus.png",
+  "images/font-button.png",
+  "images/fontchooser.png",
+  "images/frame-gap.png",
+  "images/frame.png",
+  "images/frames.png",
+  "images/gedit-shortcuts.png",
+  "images/getting-started-app10.png",
+  "images/getting-started-app1.png",
+  "images/getting-started-app2.png",
+  "images/getting-started-app3.png",
+  "images/getting-started-app4.png",
+  "images/getting-started-app6.png",
+  "images/getting-started-app7.png",
+  "images/getting-started-app8.png",
+  "images/getting-started-app9.png",
+  "images/glarea.png",
+  "images/gradient1.png",
+  "images/gradient2.png",
+  "images/gradient3.png",
+  "images/gradient4.png",
+  "images/grid.png",
+  "images/grid-packing.png",
+  "images/gtk-logo.png",
+  "images/gtk-logo.svg",
+  "images/handles.png",
+  "images/headerbar.png",
+  "images/hello-world.png",
+  "images/icon-view.png",
+  "images/image.png",
+  "images/info-bar.png",
+  "images/inspector.png",
+  "images/label.png",
+  "images/layout-btlr.png",
+  "images/layout-btrl.png",
+  "images/layout-lrbt.png",
+  "images/layout-lrtb.png",
+  "images/layout-rlbt.png",
+  "images/layout-rltb.png",
+  "images/layout-tblr.png",
+  "images/layout-tbrl.png",
+  "images/left-center.png",
+  "images/left-end.png",
+  "images/left-start.png",
+  "images/levelbar.png",
+  "images/linear.png",
+  "images/link-button.png",
+  "images/list-and-tree.png",
+  "images/list-box.png",
+  "images/lockbutton-locked.png",
+  "images/lock-button.png",
+  "images/lockbutton.png",
+  "images/lockbutton-sorry.png",
+  "images/lockbutton-unlocked.png",
+  "images/media-controls.png",
+  "images/menu.png",
+  "images/menubar.png",
+  "images/menu-button.png",
+  "images/messagedialog.png",
+  "images/multiline-text.png",
+  "images/notebook.png",
+  "images/options.png",
+  "images/overlay.png",
+  "images/pagesetupdialog.png",
+  "images/panes.png",
+  "images/password-entry.png",
+  "images/picture.png",
+  "images/popover.png",
+  "images/printdialog.png",
+  "images/progressbar.png",
+  "images/radio-button.png",
+  "images/right-center.png",
+  "images/right-end.png",
+  "images/right-start.png",
+  "images/scales.png",
+  "images/scrollbar.png",
+  "images/scrolledwindow.png",
+  "images/search-bar.png",
+  "images/search-entry.png",
+  "images/separator.png",
+  "images/shortcuts-window.png",
+  "images/sidebar.png",
+  "images/slices.png",
+  "images/sliders.png",
+  "images/spinbutton.png",
+  "images/spinner.png",
+  "images/stack.png",
+  "images/stackswitcher.png",
+  "images/statusbar.png",
+  "images/switch.png",
+  "images/toggle-button.png",
+  "images/toolbar.png",
+  "images/tree-view-coordinates.png",
+  "images/up-center.png",
+  "images/up-end.png",
+  "images/up-start.png",
+  "images/video.png",
+  "images/volumebutton.png",
+  "images/widget-hvalign.png",
+  "images/windowcontrols.png",
+  "images/window-default.png",
+  "images/window.png",
+  "images/rich-list.png",
+  "images/data-table.png",
+  "images/navigation-sidebar.png",
+]
+urlmap_file = "urlmap.js"
@@ -1,261 +0,0 @@
-#include <gtk/gtk.h>
-#include <gtk/gtkunixprint.h>
-
-gtk_about_dialog_get_type
-gtk_accessible_get_type
-gtk_actionable_get_type
-gtk_action_bar_get_type
-gtk_adjustment_get_type
-gtk_any_filter_get_type
-gtk_app_chooser_get_type
-gtk_app_chooser_button_get_type
-gtk_app_chooser_dialog_get_type
-gtk_app_chooser_widget_get_type
-gtk_application_get_type
-gtk_application_window_get_type
-gtk_aspect_frame_get_type
-gtk_assistant_get_type
-gtk_assistant_page_get_type
-gtk_at_context_get_type
-gtk_bin_layout_get_type
-gtk_bitset_get_type
-gtk_bookmark_list_get_type
-gtk_bool_filter_get_type
-gtk_box_get_type
-gtk_box_layout_get_type
-gtk_buildable_get_type
-gtk_builder_cscope_get_type
-gtk_builder_get_type
-gtk_builder_list_item_factory_get_type
-gtk_builder_scope_get_type
-gtk_button_get_type
-gtk_calendar_get_type
-gtk_cclosure_expression_get_type
-gtk_cell_area_get_type
-gtk_cell_area_box_get_type
-gtk_cell_area_context_get_type
-gtk_cell_editable_get_type
-gtk_cell_layout_get_type
-gtk_cell_renderer_accel_get_type
-gtk_cell_renderer_combo_get_type
-gtk_cell_renderer_get_type
-gtk_cell_renderer_pixbuf_get_type
-gtk_cell_renderer_progress_get_type
-gtk_cell_renderer_spin_get_type
-gtk_cell_renderer_spinner_get_type
-gtk_cell_renderer_text_get_type
-gtk_cell_renderer_toggle_get_type
-gtk_cell_view_get_type
-gtk_center_box_get_type
-gtk_center_layout_get_type
-gtk_check_button_get_type
-gtk_closure_expression_get_type
-gtk_color_button_get_type
-gtk_color_chooser_get_type
-gtk_color_chooser_dialog_get_type
-gtk_color_chooser_widget_get_type
-gtk_column_view_get_type
-gtk_column_view_column_get_type
-gtk_combo_box_get_type
-gtk_combo_box_text_get_type
-gtk_constant_expression_get_type
-gtk_constraint_get_type
-gtk_constraint_guide_get_type
-gtk_constraint_layout_get_type
-gtk_constraint_target_get_type
-gtk_css_provider_get_type
-gtk_custom_filter_get_type
-gtk_custom_sorter_get_type
-gtk_custom_layout_get_type
-gtk_dialog_get_type
-gtk_directory_list_get_type
-gtk_drag_icon_get_type
-gtk_drag_source_get_type
-gtk_drawing_area_get_type
-gtk_drop_controller_motion_get_type
-gtk_drop_down_get_type
-gtk_drop_target_async_get_type
-gtk_drop_target_get_type
-gtk_editable_get_type
-gtk_editable_label_get_type
-gtk_emoji_chooser_get_type
-gtk_entry_buffer_get_type
-gtk_entry_completion_get_type
-gtk_entry_get_type
-gtk_event_controller_get_type
-gtk_event_controller_key_get_type
-gtk_event_controller_focus_get_type
-gtk_event_controller_legacy_get_type
-gtk_event_controller_motion_get_type
-gtk_event_controller_scroll_get_type
-gtk_every_filter_get_type
-gtk_expander_get_type
-gtk_expression_get_type
-gtk_file_chooser_dialog_get_type
-gtk_file_chooser_get_type
-gtk_file_chooser_native_get_type
-gtk_file_chooser_widget_get_type
-gtk_file_filter_get_type
-gtk_filter_get_type
-gtk_filter_list_model_get_type
-gtk_fixed_get_type
-gtk_fixed_layout_get_type
-gtk_flatten_list_model_get_type
-gtk_flow_box_get_type
-gtk_flow_box_child_get_type
-gtk_font_button_get_type
-gtk_font_chooser_get_type
-gtk_font_chooser_dialog_get_type
-gtk_font_chooser_widget_get_type
-gtk_frame_get_type
-gtk_gesture_get_type
-gtk_gesture_click_get_type
-gtk_gesture_drag_get_type
-gtk_gesture_long_press_get_type
-gtk_gesture_pan_get_type
-gtk_gesture_rotate_get_type
-gtk_gesture_single_get_type
-gtk_gesture_stylus_get_type
-gtk_gesture_swipe_get_type
-gtk_gesture_zoom_get_type
-gtk_gl_area_get_type
-gtk_grid_get_type
-gtk_grid_layout_child_get_type
-gtk_grid_layout_get_type
-gtk_grid_view_get_type
-gtk_header_bar_get_type
-gtk_icon_theme_get_type
-gtk_icon_view_get_type
-gtk_image_get_type
-gtk_im_context_get_type
-gtk_im_context_simple_get_type
-gtk_im_multicontext_get_type
-gtk_info_bar_get_type
-gtk_label_get_type
-gtk_layout_child_get_type
-gtk_layout_manager_get_type
-gtk_link_button_get_type
-gtk_list_item_get_type
-gtk_list_item_factory_get_type
-gtk_list_store_get_type
-gtk_list_box_get_type
-gtk_list_box_row_get_type
-gtk_list_view_get_type
-gtk_lock_button_get_type
-gtk_map_list_model_get_type
-gtk_media_controls_get_type
-gtk_media_file_get_type
-gtk_media_stream_get_type
-gtk_menu_button_get_type
-gtk_message_dialog_get_type
-gtk_mount_operation_get_type
-gtk_multi_filter_get_type
-gtk_multi_selection_get_type
-gtk_multi_sorter_get_type
-gtk_native_get_type
-gtk_native_dialog_get_type
-gtk_no_selection_get_type
-gtk_notebook_get_type
-gtk_notebook_page_get_type
-gtk_numeric_sorter_get_type
-gtk_object_expression_get_type
-gtk_orientable_get_type
-gtk_overlay_get_type
-gtk_overlay_layout_get_type
-gtk_overlay_layout_child_get_type
-gtk_pad_controller_get_type
-gtk_page_setup_get_type
-@DISABLE_ON_W32@gtk_page_setup_unix_dialog_get_type
-gtk_paned_get_type
-gtk_paper_size_get_type
-gtk_password_entry_get_type
-gtk_picture_get_type
-gtk_popover_get_type
-gtk_popover_menu_get_type
-gtk_popover_menu_bar_get_type
-@DISABLE_ON_W32@gtk_printer_get_type
-gtk_print_context_get_type
-@DISABLE_ON_W32@gtk_print_job_get_type
-gtk_print_operation_get_type
-gtk_print_operation_preview_get_type
-gtk_print_settings_get_type
-@DISABLE_ON_W32@gtk_print_unix_dialog_get_type
-gtk_progress_bar_get_type
-gtk_property_expression_get_type
-gtk_range_get_type
-gtk_recent_manager_get_type
-gtk_revealer_get_type
-gtk_root_get_type
-gtk_scale_button_get_type
-gtk_scale_get_type
-gtk_scrollable_get_type
-gtk_scrollbar_get_type
-gtk_scrolled_window_get_type
-gtk_search_bar_get_type
-gtk_search_entry_get_type
-gtk_selection_filter_model_get_type
-gtk_selection_model_get_type
-gtk_separator_get_type
-gtk_settings_get_type
-gtk_shortcut_get_type
-gtk_shortcut_controller_get_type
-gtk_shortcut_label_get_type
-gtk_shortcut_manager_get_type
-gtk_shortcuts_window_get_type
-gtk_shortcuts_section_get_type
-gtk_shortcuts_group_get_type
-gtk_shortcuts_shortcut_get_type
-gtk_signal_list_item_factory_get_type
-gtk_single_selection_get_type
-gtk_size_group_get_type
-gtk_slice_list_model_get_type
-gtk_snapshot_get_type
-gtk_sort_list_model_get_type
-gtk_sorter_get_type
-gtk_spin_button_get_type
-gtk_spinner_get_type
-gtk_stack_get_type
-gtk_stack_page_get_type
-gtk_stack_sidebar_get_type
-gtk_stack_switcher_get_type
-gtk_statusbar_get_type
-gtk_string_filter_get_type
-gtk_string_list_get_type
-gtk_string_object_get_type
-gtk_string_sorter_get_type
-gtk_switch_get_type
-gtk_level_bar_get_type
-gtk_style_context_get_type
-gtk_style_provider_get_type
-gtk_text_buffer_get_type
-gtk_text_child_anchor_get_type
-gtk_text_get_type
-gtk_text_iter_get_type
-gtk_text_mark_get_type
-gtk_text_tag_get_type
-gtk_text_tag_table_get_type
-gtk_text_view_get_type
-gtk_toggle_button_get_type
-gtk_tree_drag_dest_get_type
-gtk_tree_drag_source_get_type
-gtk_tree_expander_get_type
-gtk_tree_list_model_get_type
-gtk_tree_list_row_get_type
-gtk_tree_list_row_sorter_get_type
-gtk_tree_model_filter_get_type
-gtk_tree_model_get_type
-gtk_tree_model_sort_get_type
-gtk_tree_selection_get_type
-gtk_tree_sortable_get_type
-gtk_tree_store_get_type
-gtk_tree_view_column_get_type
-gtk_tree_view_get_type
-gtk_video_get_type
-gtk_viewport_get_type
-gtk_volume_button_get_type
-gtk_widget_get_type
-gtk_widget_paintable_get_type
-gtk_window_get_type
-gtk_window_controls_get_type
-gtk_window_group_get_type
-gtk_window_handle_get_type
@@ -0,0 +1,138 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="128"
+   height="128"
+   id="svg6843"
+   sodipodi:version="0.32"
+   inkscape:version="0.92.4 5da689c313, 2019-01-14"
+   version="1.0"
+   sodipodi:docname="gtk-logo.svg"
+   inkscape:output_extension="org.inkscape.output.svg.inkscape"
+   inkscape:export-filename="/home/ebassi/Pictures/gtk-logo-256.png"
+   inkscape:export-xdpi="192"
+   inkscape:export-ydpi="192">
+  <defs
+     id="defs6845">
+    <inkscape:perspective
+       sodipodi:type="inkscape:persp3d"
+       inkscape:vp_x="-50 : 600 : 1"
+       inkscape:vp_y="0 : 1000 : 0"
+       inkscape:vp_z="700 : 600 : 1"
+       inkscape:persp3d-origin="300 : 400 : 1"
+       id="perspective13" />
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="2.8284271"
+     inkscape:cx="69.874353"
+     inkscape:cy="64.313526"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     inkscape:document-units="px"
+     inkscape:grid-bbox="true"
+     width="128px"
+     height="128px"
+     showguides="true"
+     inkscape:guide-bbox="true"
+     inkscape:window-width="1920"
+     inkscape:window-height="1016"
+     inkscape:window-x="0"
+     inkscape:window-y="27"
+     inkscape:window-maximized="1">
+    <inkscape:grid
+       type="xygrid"
+       id="grid7947" />
+  </sodipodi:namedview>
+  <metadata
+     id="metadata6848">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title />
+        <dc:date />
+        <dc:creator>
+          <cc:Agent>
+            <dc:title />
+          </cc:Agent>
+        </dc:creator>
+        <dc:rights>
+          <cc:Agent>
+            <dc:title />
+          </cc:Agent>
+        </dc:rights>
+        <dc:publisher>
+          <cc:Agent>
+            <dc:title />
+          </cc:Agent>
+        </dc:publisher>
+        <dc:identifier />
+        <dc:source />
+        <dc:relation />
+        <dc:language />
+        <dc:subject>
+          <rdf:Bag />
+        </dc:subject>
+        <dc:coverage />
+        <dc:description />
+        <dc:contributor>
+          <cc:Agent>
+            <dc:title />
+          </cc:Agent>
+        </dc:contributor>
+        <cc:license
+           rdf:resource="" />
+      </cc:Work>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     id="layer1"
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer">
+    <path
+       sodipodi:nodetypes="ccccc"
+       id="path6976"
+       d="M 20.88413,30.82696 L 53.816977,55.527708 L 107.33282,39.060543 L 70.587303,17.177763 L 20.88413,30.82696 z"
+       style="fill:#729fcf;fill-opacity:1;fill-rule:evenodd;stroke:#ffffff;stroke-width:2.12364459;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;display:inline" />
+    <path
+       id="path6978"
+       d="M 22.94243,82.287118 L 20.88413,30.82696 L 53.816977,55.527708 L 53.816977,111.10486 L 22.94243,82.287118 z"
+       style="fill:#e40000;fill-opacity:1;fill-rule:evenodd;stroke:#ffffff;stroke-width:2.12364459;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;display:inline" />
+    <path
+       id="path6980"
+       d="M 53.816977,111.10486 L 103.21619,90.5207 L 107.33282,39.060543 L 53.816977,55.527708 L 53.816977,111.10486 z"
+       style="fill:#7fe719;fill-opacity:1;fill-rule:evenodd;stroke:#ffffff;stroke-width:2.12364459;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;display:inline" />
+    <path
+       sodipodi:nodetypes="ccc"
+       id="path6982"
+       d="M 23.216626,81.319479 L 70.48573,67.361442 L 103.38422,90.444516"
+       style="opacity:1;fill:none;fill-rule:evenodd;stroke:#ffffff;stroke-width:1.25;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
+    <path
+       sodipodi:nodetypes="cc"
+       id="path6984"
+       d="M 70.434539,17.875593 L 70.434539,66.984877"
+       style="opacity:1;fill:#babdb6;fill-rule:evenodd;stroke:#ffffff;stroke-width:1.25;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
+  </g>
+</svg>
@@ -0,0 +1,70 @@
+----
+Title: Initialization
+----
+
+# Library initialization and main loop
+
+Before using GTK, you need to initialize it using [func@Gtk.init]; this
+connects to the windowing system, sets up the locale and performs other
+initialization tasks. [func@Gtk.init] exits the application if errors occur;
+to avoid this, you can use [`func@Gtk.init_check`], which allows you to recover
+from a failed GTK initialization; for instance, you might start up your
+application in text mode instead.
+
+Like most GUI toolkits, GTK uses an event-driven programming model. When the
+application is doing nothing, GTK sits in the “main loop” and waits for input.
+If the user performs some action - say, a mouse click - then the main loop
+“wakes up” and delivers an event to GTK. GTK forwards the event to one or
+more widgets.
+
+When widgets receive an event, they frequently emit one or more “signals”.
+Signals notify your program that "something interesting happened" by invoking
+functions you’ve connected to the signal with `g_signal_connect()`. Functions
+connected to a signal are often called “callbacks”.
+
+When your callbacks are invoked, you would typically take some action - for
+example, when an Open button is clicked you might display a [class@Gtk.FileChooserDialog].
+After a callback finishes, GTK will return to the main loop and await more
+user input.
+
+### The `main()` function for a simple GTK application
+
+```c
+int
+main (int argc, char **argv)
+{
+ GtkWidget *window;
+  // Initialize i18n support with bindtextdomain(), etc.
+
+  // ...
+
+  // Initialize the widget set
+  gtk_init ();
+
+  // Create the main window
+  window = gtk_window_new ();
+
+  // Set up our GUI elements
+
+  // ...
+
+  // Show the application window
+  gtk_widget_show (window);
+
+  // Enter the main event loop, and wait for user interaction
+  while (!done)
+    g_main_context_iteration (NULL, TRUE);
+
+  // The user lost interest
+  return 0;
+}
+```
+
+It's important to note that if you use [class@Gtk.Application], the
+application class will take care of initializing GTK for you, as well
+as spinning the main loop.
+
+### See also
+
+  - the GLib manual, especially `GMainLoop`
+  - signal-related functions, such as `g_signal_connect()` in GObject
@@ -1,4 +1,5 @@
-# Overview of GTK input and event handling {#input-overview}
+Title: Overview of GTK input and event handling
+Slug: input-overview

 This chapter describes in detail how GTK handles input. If you are interested
 in what happens to translate a key press or mouse motion of the users into a
@@ -10,7 +11,7 @@ be useful if you decide to implement your own widgets.
 The most basic input devices that every computer user has interacted with are
 keyboards and mice; beyond these, GTK supports touchpads, touchscreens and
 more exotic input devices such as graphics tablets. Inside GTK, every such
-input device is represented by a #GdkDevice object.
+input device is represented by a `GdkDevice` object.

 To simplify dealing with the variability between these input devices, GTK
 has a concept of logical and physical devices. The concrete physical devices that
@@ -29,9 +30,9 @@ These are typically directed at a specific surface - for pointer events,
 the surface under the pointer (grabs complicate this), for keyboard events,
 the surface with the keyboard focus.

-GDK translates these raw windowing system events into #GdkEvents.
+GDK translates these raw windowing system events into `GdkEvents`.
 Typical input events are button clicks, pointer motion, key presses
-or touch events. These are all represented as #GdkEvents, but you can
+or touch events. These are all represented as `GdkEvents`, but you can
 differentiate between different events by looking at their type, using
 gdk_event_get_event_type().

@@ -40,12 +41,12 @@ are connected in to each other in an “event sequence” that
 univocally identifies events that are related to the same
 interaction.

-When GTK creates a GdkSurface, it connects to the #GdkSurface::event
+When GTK creates a `GdkSurface`, it connects to the ::event
 signal on it, which receives all of these input events. Surfaces have
 have signals and properties, e.g. to deal with window management
 related events.

-## Event propagation {#event-propagation}
+## Event propagation

 The function which initially receives input events on the GTK
 side is responsible for a number of tasks.
@@ -56,7 +57,7 @@ side is responsible for a number of tasks.
 3. Send the event to widgets.

 An event is propagated down and up the widget hierarchy in three phases
-(see #GtkPropagationPhase) towards a target widget.
+towards a target widget.

 ![Event propagation phases](capture-bubble.png)

@@ -69,8 +70,8 @@ For pointer events, the target widget is determined by picking
 the widget at the events coordinates (see gtk_widget_pick()).

 In the first phase (the “capture” phase) the event is delivered to
-each widget from the top-most (the top-level #GtkWindow or grab widget)
-down to the target #GtkWidget.
+each widget from the top-most (the top-level `GtkWindow` or grab widget)
+down to the target widget.
 [Event controllers](event-controllers-and-gestures) that are attached
 with %GTK_PHASE_CAPTURE get a chance to react to the event.

@@ -94,12 +95,11 @@ below to learn more about gestures and sequences.

 ## Keyboard input

-Every #GtkWindow maintains a single focus location (in
-the #GtkWindow:focus-widget property). The focus widget is the
-target widget for key events sent to the window. Only widgets which
-have #GtkWidget:can-focus set to %TRUE can become the focus. Typically
-these are input controls such as entries or text fields, but e.g.
-buttons can take the focus too.
+Every `GtkWindow` maintains a single focus location (in the :focus-widget
+property). The focus widget is the target widget for key events sent to
+the window. Only widgets which have :focusable set to %TRUE can become
+the focus. Typically these are input controls such as entries or text
+fields, but e.g. buttons can take the focus too.

 Input widgets can be given the focus by clicking on them, but focus
 can also be moved around with certain key events (this is known as
@@ -125,7 +125,7 @@ GTK has traditionally supported different kinds of shortcuts:
 - Mnemonics are usually triggered using Alt as a modifier for a letter.
  They are used in places where a label is associated with a control,
  and are indicated by underlining the letter in the label. As a special
-  case, inside menus (i.e. inside #GtkPopoverMenu), mnemonics can be
+  case, inside menus (i.e. inside `GtkPopoverMenu`), mnemonics can be
  triggered without the modifier.
 - Key bindings are specific to individual widgets, such as Ctrl-C or
  Ctrl-V in an entry copy to or paste from the clipboard. They are only
@@ -134,15 +134,15 @@ GTK has traditionally supported different kinds of shortcuts:
 GTK handles accelerators and mnemonics in a global scope, during the
 capture phase, and key bindings locally, during the target phase.

-Under the hood, all shortcuts are represented as instances of #GtkShortcut,
-and they are managed by #GtkShortcutController.
+Under the hood, all shortcuts are represented as instances of `GtkShortcut`,
+and they are managed by `GtkShortcutController`.

-## Event controllers and gestures {#event-controllers-and-gestures}
+## Event controllers and gestures

 Event controllers are standalone objects that can perform
-specific actions upon received #GdkEvents. These are tied
-to a #GtkWidget, and can be told of the event propagation
-phase at which they will manage the events.
+specific actions upon received `GdkEvents`. These are tied
+to a widget, and can be told of the event propagation phase
+at which they will manage the events.

 Gestures are a set of specific controllers that are prepared
 to handle pointer and/or touch events, each gesture
@@ -167,10 +167,10 @@ gestures. Some examples of grouping may be:
 - If “press” and “long press” are wanted simultaneously,
  those would need grouping.

-Shortcuts are handled by #GtkShortcutController, which is
+Shortcuts are handled by `GtkShortcutController`, which is
 a complex event handler that can either activate shortcuts
 itself, or propagate them to another controller, depending
-on its #GtkShortcutController:scope.
+on its scope.

 ## Gesture states

@@ -1,478 +1,13 @@
-fs = import('fs')
-
-private_headers = [
-  'gtkaccelgroupprivate.h',
-  'gtkaccelmapprivate.h',
-  'gtkaccessibleattributesetprivate.h',
-  'gtkaccessibleattributevalueprivate.h',
-  'gtkaccessibleprivate.h',
-  'gtkaccessiblevalueprivate.h',
-  'gtkactionhelperprivate.h',
-  'gtkactionmuxerprivate.h',
-  'gtkactionobservableprivate.h',
-  'gtkactionobserverprivate.h',
-  'gtkadjustmentprivate.h',
-  'gtkallocatedbitmaskprivate.h',
-  'gtkappchooserprivate.h',
-  'gtkapplicationaccelsprivate.h',
-  'gtkapplicationprivate.h',
-  'gtkatcontextprivate.h',
-  'gtkbindingsprivate.h',
-  'gtkbitmaskprivateimpl.h',
-  'gtkbitmaskprivate.h',
-  'gtkbuildableprivate.h',
-  'gtkbuilderprivate.h',
-  'gtkbuilderscopeprivate.h',
-  'gtkbuiltiniconprivate.h',
-  'gtkbuttonprivate.h',
-  'gtkcellareaboxcontextprivate.h',
-  'gtkcheckbuttonprivate.h',
-  'gtkcolorchooserprivate.h',
-  'gtkcoloreditorprivate.h',
-  'gtkcolorpickerkwinprivate.h',
-  'gtkcolorpickerportalprivate.h',
-  'gtkcolorpickerprivate.h',
-  'gtkcolorpickershellprivate.h',
-  'gtkcolorplaneprivate.h',
-  'gtkcolorscaleprivate.h',
-  'gtkcolorswatchprivate.h',
-  'gtkcolumnlistitemfactoryprivate.h',
-  'gtkcolumnviewcellprivate.h',
-  'gtkcolumnviewcolumnprivate.h',
-  'gtkcolumnviewlayoutprivate.h',
-  'gtkcolumnviewprivate.h',
-  'gtkcolumnviewsorterprivate.h',
-  'gtkcolumnviewtitleprivate.h',
-  'gtkcomboboxprivate.h',
-  'gtkcomposetable.h',
-  'gtkconstraintexpressionprivate.h',
-  'gtkconstraintguideprivate.h',
-  'gtkconstraintlayoutprivate.h',
-  'gtkconstraintprivate.h',
-  'gtkconstraintsolverprivate.h',
-  'gtkconstrainttypesprivate.h',
-  'gtkconstraintvflparserprivate.h',
-  'gtkcountingbloomfilterprivate.h',
-  'gtkcssanimatedstyleprivate.h',
-  'gtkcssanimationprivate.h',
-  'gtkcssarrayvalueprivate.h',
-  'gtkcssbgsizevalueprivate.h',
-  'gtkcssbordervalueprivate.h',
-  'gtkcssboxesimplprivate.h',
-  'gtkcssboxesprivate.h',
-  'gtkcsscalcvalueprivate.h',
-  'gtkcsscolorvalueprivate.h',
-  'gtkcsscornervalueprivate.h',
-  'gtkcssdataurlprivate.h',
-  'gtkcssdimensionvalueprivate.h',
-  'gtkcssdynamicprivate.h',
-  'gtkcsseasevalueprivate.h',
-  'gtkcssenumvalueprivate.h',
-  'gtkcssfiltervalueprivate.h',
-  'gtkcssfontfeaturesvalueprivate.h',
-  'gtkcssfontvariationsvalueprivate.h',
-  'gtkcssiconthemevalueprivate.h',
-  'gtkcssimageconicprivate.h',
-  'gtkcssimagecrossfadeprivate.h',
-  'gtkcssimagefallbackprivate.h',
-  'gtkcssimageiconthemeprivate.h',
-  'gtkcssimageinvalidprivate.h',
-  'gtkcssimagelinearprivate.h',
-  'gtkcssimagepaintableprivate.h',
-  'gtkcssimageprivate.h',
-  'gtkcssimageradialprivate.h',
-  'gtkcssimagerecolorprivate.h',
-  'gtkcssimagescaledprivate.h',
-  'gtkcssimageurlprivate.h',
-  'gtkcssimagevalueprivate.h',
-  'gtkcssimagewin32private.h',
-  'gtkcssinheritvalueprivate.h',
-  'gtkcssinitialvalueprivate.h',
-  'gtkcsskeyframesprivate.h',
-  'gtkcsslocationprivate.h',
-  'gtkcsslookupprivate.h',
-  'gtkcssmatcherprivate.h',
-  'gtkcssnodedeclarationprivate.h',
-  'gtkcssnodeprivate.h',
-  'gtkcssnodestylecacheprivate.h',
-  'gtkcssnumbervalueprivate.h',
-  'gtkcsspalettevalueprivate.h',
-  'gtkcssparserprivate.h',
-  'gtkcsspathnodeprivate.h',
-  'gtkcsspositionvalueprivate.h',
-  'gtkcssproviderprivate.h',
-  'gtkcssrepeatvalueprivate.h',
-  'gtkcssrgbavalueprivate.h',
-  'gtkcsssectionprivate.h',
-  'gtkcssselectorprivate.h',
-  'gtkcssserializerprivate.h',
-  'gtkcssshadowsvalueprivate.h',
-  'gtkcssshadowvalueprivate.h',
-  'gtkcssshorthandpropertyprivate.h',
-  'gtkcssstaticstyleprivate.h',
-  'gtkcssstringvalueprivate.h',
-  'gtkcssstylechangeprivate.h',
-  'gtkcssstyleprivate.h',
-  'gtkcssstylepropertyprivate.h',
-  'gtkcsstokenizerprivate.h',
-  'gtkcsstransformvalueprivate.h',
-  'gtkcsstransientnodeprivate.h',
-  'gtkcsstransitionprivate.h',
-  'gtkcsstypesprivate.h',
-  'gtkcssunsetvalueprivate.h',
-  'gtkcssvalueprivate.h',
-  'gtkcsswidgetnodeprivate.h',
-  'gtkcsswin32sizevalueprivate.h',
-  'gtkdialogprivate.h',
-  'gtkdragdestprivate.h',
-  'gtkdropprivate.h',
-  'gtkemojicompletion.h',
-  'gtkentryprivate.h',
-  'gtkeventcontrollerlegacyprivate.h',
-  'gtkeventcontrollerprivate.h',
-  'gtkfilechoosererrorstackprivate.h',
-  'gtkfilechoosernativeprivate.h',
-  'gtkfilechooserprivate.h',
-  'gtkfilechooserwidgetprivate.h',
-  'gtkfilefilterprivate.h',
-  'gtkflowboxprivate.h',
-  'gtkfontchooserprivate.h',
-  'gtkfontchooserwidgetprivate.h',
-  'gtkgesturedragprivate.h',
-  'gtkgesturelongpressprivate.h',
-  'gtkgesturemultipressprivate.h',
-  'gtkgesturepanprivate.h',
-  'gtkgestureprivate.h',
-  'gtkgesturerotateprivate.h',
-  'gtkgesturesingleprivate.h',
-  'gtkgesturestylusprivate.h',
-  'gtkgestureswipeprivate.h',
-  'gtkgesturezoomprivate.h',
-  'gtkgizmoprivate.h',
-  'gtkheaderbarprivate.h',
-  'gtkhslaprivate.h',
-  'gtkiconcacheprivate.h',
-  'gtkiconcachevalidatorprivate.h',
-  'gtkiconhelperprivate.h',
-  'gtkiconprivate.h',
-  'gtkiconthemeprivate.h',
-  'gtkiconviewprivate.h',
-  'gtkimagedefinitionprivate.h',
-  'gtkimageprivate.h',
-  'gtkimcontextbroadway.h',
-  'gtkimcontextime.h',
-  'gtkimcontextquartz.h',
-  'gtkimcontextsimpleprivate.h',
-  'gtkimcontextsimpleseqs.h',
-  'gtkimcontextwayland.h',
-  'gtkimmoduleprivate.h',
-  'gtkimmodule.h',
-  'gtkintl.h',
-  'gtkistringprivate.h',
-  'gtkkineticscrollingprivate.h',
-  'gtklabelprivate.h',
-  'gtklayoutmanagerprivate.h',
-  'gtklistbaseprivate.h',
-  'gtklistitemprivate.h',
-  'gtklistitemfactoryprivate.h',
-  'gtklistitemmanagerprivate.h',
-  'gtklistitemwidgetprivate.h',
-  'gtklistlistmodelprivate.h',
-  'gtklockbuttonprivate.h',
-  'gtkmagnifierprivate.h',
-  'gtkmediafileprivate.h',
-  'gtkmenubuttonprivate.h',
-  'gtkmenusectionboxprivate.h',
-  'gtkmenutrackeritemprivate.h',
-  'gtkmenutrackerprivate.h',
-  'gtkmodelbuttonprivate.h',
-  'gtkmodulesprivate.h',
-  'gtkmountoperationprivate.h',
-  'gtknativedialogprivate.h',
-  'gtknativeprivate.h',
-  'gtknomediafileprivate.h',
-  'gtkpango.h',
-  'gtkpasswordentrybufferprivate.h',
-  'gtkpasswordentryprivate.h',
-  'gtkpathbar.h',
-  'gdkpixbufutilsprivate.h',
-  'gtkplacessidebarprivate.h',
-  'gtkplacesviewprivate.h',
-  'gtkplacesviewrowprivate.h',
-  'gtkpointerfocusprivate.h',
-  'gtkpopcountprivate.h',
-  'gtkpopovermenubarprivate.h',
-  'gtkpopovermenuprivate.h',
-  'gtkpopoverprivate.h',
-  'gtkprintbackendprivate.h',
-  'gtkprinterprivate.h',
-  'gtkprintoperation-portal.h',
-  'gtkprintoperation-private.h',
-  'gtkprintutils.h',
-  'gtkprivate.h',
-  'gtkprogresstrackerprivate.h',
-  'gtkpropertylookuplistmodelprivate.h',
-  'gtkquery.h',
-  'gtkrangeprivate.h',
-  'gtkrbtreeprivate.h',
-  'gtkrenderbackgroundprivate.h',
-  'gtkrenderborderprivate.h',
-  'gtkrendericonprivate.h',
-  'gtkrendernodepaintableprivate.h',
-  'gtkrootprivate.h',
-  'gtkroundedboxprivate.h',
-  'gtkscalerprivate.h',
-  'gtksearchengine.h',
-  'gtksearchenginemodel.h',
-  'gtksearchenginequartz.h',
-  'gtksearchenginetracker3.h',
-  'gtksearchentryprivate.h',
-  'gtksecurememoryprivate.h',
-  'gtksettingsprivate.h',
-  'gtkshortcutactionprivate.h',
-  'gtkshortcutcontrollerprivate.h',
-  'gtkshortcutmanagerprivate.h',
-  'gtkshortcutsshortcutprivate.h',
-  'gtkshortcutswindowprivate.h',
-  'gtksidebarrowprivate.h',
-  'gtksizegroup-private.h',
-  'gtksizerequestcacheprivate.h',
-  'gtksnapshotprivate.h',
-  'gtksorterprivate.h',
-  'gtksortkeysprivate.h',
-  'gtkspinbuttonprivate.h',
-  'gtkstyleanimationprivate.h',
-  'gtkstylecascadeprivate.h',
-  'gtkstylecontextprivate.h',
-  'gtkstylepropertyprivate.h',
-  'gtkstyleproviderprivate.h',
-  'gtktestatcontextprivate.h',
-  'gtktextattributes.h',
-  'gtktextbufferprivate.h',
-  'gtktextchildprivate.h',
-  'gtktextdisplayprivate.h',
-  'gtktexthandleprivate.h',
-  'gtktexthistoryprivate.h',
-  'gtktextiterprivate.h',
-  'gtktextlayoutprivate.h',
-  'gtktextlinedisplaycacheprivate.h',
-  'gtktextmarkprivate.h',
-  'gtktextprivate.h',
-  'gtktextsegment.h',
-  'gtktexttagprivate.h',
-  'gtktextutil.h',
-  'gtktextviewchildprivate.h',
-  'gtktextviewprivate.h',
-  'gtktogglebuttonprivate.h',
-  'gtktoolbarprivate.h',
-  'gtktooltipprivate.h',
-  'gtktooltipwindowprivate.h',
-  'gtktreedatalist.h',
-  'gtktreepopoverprivate.h',
-  'gtktreeprivate.h',
-  'gtktreerbtreeprivate.h',
-  'gtkutilsprivate.h',
-  'gtkwidgetpaintableprivate.h',
-  'gtkwidgetpathprivate.h',
-  'gtkwidgetprivate.h',
-  'gtkwin32drawprivate.h',
-  'gtkwin32themeprivate.h',
-  'gtkwindowprivate.h',
-
-  'gsettings-mapping.h',
-  'gskpango.h',
-  'gtkdbusgenerated.h',
-  'imm-extra.h',
-  'language-names.h',
-  'open-type-layout.h',
-  'script-names.h',
-  'text-input-unstable-v3-client-protocol.h',
-
-  'a11y',
-  'inspector',
-  'roaring',
-  'timsort',
-  'tools',
-]
-
-images = [
-  'images/aboutdialog.png',
-  'images/action-bar.png',
-  'images/appchooserbutton.png',
-  'images/appchooserdialog.png',
-  'images/arrows.png',
-  'images/assistant.png',
-  'images/background.png',
-  'images/bloatpad-gnome.png',
-  'images/bloatpad-osx.png',
-  'images/bloatpad-xfce.png',
-  'images/border1.png',
-  'images/border2.png',
-  'images/border3.png',
-  'images/box.png',
-  'images/box-expand.png',
-  'images/box-packing.png',
-  'images/builder-shortcuts.png',
-  'images/button.png',
-  'images/calendar.png',
-  'images/capture-bubble.png',
-  'images/centerbox.png',
-  'images/check-button.png',
-  'images/checks.png',
-  'images/clocks-shortcuts.png',
-  'images/color-button.png',
-  'images/colorchooser.png',
-  'images/combo-box-entry.png',
-  'images/combo-box.png',
-  'images/combo-box-text.png',
-  'images/down-center.png',
-  'images/down-end.png',
-  'images/down-start.png',
-  'images/drop-down.png',
-  'images/drawing.png',
-  'images/drawingarea.png',
-  'images/ease-in-out.png',
-  'images/ease-in.png',
-  'images/ease-out.png',
-  'images/ease.png',
-  'images/editable-label.png',
-  'images/emojichooser.png',
-  'images/entry.png',
-  'images/exampleapp.png',
-  'images/expanders.png',
-  'images/expander.png',
-  'images/extensions.png',
-  'images/figure-hierarchical-drawing.png',
-  'images/figure-windowed-label.png',
-  'images/file-button.png',
-  'images/filechooser.png',
-  'images/flow-box.png',
-  'images/focus.png',
-  'images/font-button.png',
-  'images/fontchooser.png',
-  'images/frame-gap.png',
-  'images/frame.png',
-  'images/frames.png',
-  'images/gedit-shortcuts.png',
-  'images/getting-started-app10.png',
-  'images/getting-started-app1.png',
-  'images/getting-started-app2.png',
-  'images/getting-started-app3.png',
-  'images/getting-started-app4.png',
-  'images/getting-started-app6.png',
-  'images/getting-started-app7.png',
-  'images/getting-started-app8.png',
-  'images/getting-started-app9.png',
-  'images/glarea.png',
-  'images/gradient1.png',
-  'images/gradient2.png',
-  'images/gradient3.png',
-  'images/gradient4.png',
-  'images/grid.png',
-  'images/grid-packing.png',
-  'images/handles.png',
-  'images/headerbar.png',
-  'images/hello-world.png',
-  'images/icon-view.png',
-  'images/image.png',
-  'images/info-bar.png',
-  'images/inspector.png',
-  'images/label.png',
-  'images/layout-btlr.png',
-  'images/layout-btrl.png',
-  'images/layout-lrbt.png',
-  'images/layout-lrtb.png',
-  'images/layout-rlbt.png',
-  'images/layout-rltb.png',
-  'images/layout-tblr.png',
-  'images/layout-tbrl.png',
-  'images/left-center.png',
-  'images/left-end.png',
-  'images/left-start.png',
-  'images/levelbar.png',
-  'images/linear.png',
-  'images/link-button.png',
-  'images/list-and-tree.png',
-  'images/list-box.png',
-  'images/lockbutton-locked.png',
-  'images/lock-button.png',
-  'images/lockbutton.png',
-  'images/lockbutton-sorry.png',
-  'images/lockbutton-unlocked.png',
-  'images/media-controls.png',
-  'images/menu.png',
-  'images/menubar.png',
-  'images/menu-button.png',
-  'images/messagedialog.png',
-  'images/multiline-text.png',
-  'images/notebook.png',
-  'images/options.png',
-  'images/overlay.png',
-  'images/pagesetupdialog.png',
-  'images/panes.png',
-  'images/password-entry.png',
-  'images/picture.png',
-  'images/popover.png',
-  'images/printdialog.png',
-  'images/progressbar.png',
-  'images/right-center.png',
-  'images/right-end.png',
-  'images/right-start.png',
-  'images/scales.png',
-  'images/scrollbar.png',
-  'images/scrolledwindow.png',
-  'images/search-bar.png',
-  'images/search-entry.png',
-  'images/separator.png',
-  'images/shortcuts-window.png',
-  'images/sidebar.png',
-  'images/slices.png',
-  'images/sliders.png',
-  'images/spinbutton.png',
-  'images/spinner.png',
-  'images/stack.png',
-  'images/stackswitcher.png',
-  'images/statusbar.png',
-  'images/switch.png',
-  'images/toggle-button.png',
-  'images/toolbar.png',
-  'images/tree-view-coordinates.png',
-  'images/up-center.png',
-  'images/up-end.png',
-  'images/up-start.png',
-  'images/video.png',
-  'images/volumebutton.png',
-  'images/widget-hvalign.png',
-  'images/windowcontrols.png',
-  'images/window-default.png',
-  'images/window.png',
-  'images/rich-list.png',
-  'images/data-table.png',
-  'images/navigation-sidebar.png'
-]
-
-content_files = [
-  'gtk4-broadwayd.xml',
-  'gtk4-builder-tool.xml',
-  'gtk4-demo-application.xml',
-  'gtk4-demo.xml',
-  'gtk4-encode-symbolic-svg.xml',
-  'gtk4-icon-browser.xml',
-  'gtk4-launch.xml',
-  'gtk4-query-settings.xml',
-  'gtk4-update-icon-cache.xml',
-  'gtk4-widget-factory.xml',
-  'overview.xml',
-  'visual_index.xml',
-]
-
+# XXX: gi-docgen needs a deps file
 expand_content_md_files = [
+  'overview.md',
  'broadway.md',
  'osx.md',
  'wayland.md',
  'windows.md',
  'x11.md',
  'getting_started.md',
+  'initialization.md',
  'resources.md',
  'building.md',
  'compiling.md',
@@ -489,69 +24,31 @@ expand_content_md_files = [
  'section-tree-widget.md',
  'section-list-widget.md',
  'question_index.md',
+  'visual_index.md'
 ]

-types_conf = configuration_data()
-if os_win32
-  types_conf.set('DISABLE_ON_W32', '%')
-else
-  types_conf.set('DISABLE_ON_W32', '')
-endif
-
-if os_darwin
-  types_conf.set('DISABLE_ON_QUARTZ', '%')
-else
-  types_conf.set('DISABLE_ON_QUARTZ', '')
-endif
+gtk4_toml = configure_file(input: 'gtk4.toml.in', output: 'gtk4.toml', configuration: toml_conf)

 if get_option('gtk_doc')
-  configure_file(input: 'version.xml.in', output: 'version.xml', configuration: version_conf)
-
-  # gtk-markdown-to-docbook uses pandoc
-  pandoc = find_program('pandoc', required: true)
-  expand_md = find_program('gtk-markdown-to-docbook')
-  expand_md_targets = []
-  foreach t : expand_content_md_files
-    expand_md_targets += custom_target(t,
-      input: [ t ],
-      output: [ fs.replace_suffix(t, '.xml') ],
-      command: [ expand_md, '@INPUT@', '@OUTPUT@'],
-    )
-  endforeach
-
-  gnome.gtkdoc('gtk4',
-    mode: 'none',
-    main_xml: 'gtk4-docs.xml',
-    src_dir: [
-      gtkinc,
+  custom_target('gtk4-doc',
+    input: [ gtk4_toml, gtk_gir[0] ],
+    output: 'gtk4',
+    command: [
+      gidocgen,
+      'generate',
+      '--quiet',
+      '--add-include-path=@0@'.format(meson.current_build_dir() / '../../../gtk'),
+      '--config=@INPUT0@',
+      '--output-dir=@OUTPUT@',
+      '--no-namespace-dir',
+      '--content-dir=@0@'.format(meson.current_source_dir()),
+      '@INPUT1@',
    ],
-    dependencies: libgtk_dep,
-    gobject_typesfile: configure_file(
-      input: 'gtk4.types.in',
-      output: 'gtk4.types',
-      configuration: types_conf,
-    ),
-    scan_args: [
-      '--ignore-decorators=_GDK_EXTERN|G_GNUC_WARN_UNUSED_RESULT',
-      '--ignore-headers=' + ' '.join(private_headers),
-    ],
-    mkdb_args: [
-      '--default-includes=gtk/gtk.h',
-      '--ignore-files=' + ' '.join(private_headers),
-    ],
-    fixxref_args: [
-      '--html-dir=@0@'.format(docpath),
-      '--extra-dir=@0@'.format(join_paths(glib_docpath, 'glib')),
-      '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gobject')),
-      '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gio')),
-      '--extra-dir=@0@'.format(cairo_docpath),
-      '--extra-dir=@0@'.format(gdkpixbuf_docpath),
-      '--extra-dir=../gdk',
-      '--extra-dir=../gsk',
-    ],
-    content_files: content_files + expand_md_targets,
-    html_assets: images,
+    depends: [ gdk_gir[0], gsk_gir[0] ],
+    depend_files: [ expand_content_md_files ],
+    build_by_default: true,
    install: true,
+    install_dir: docs_dir,
  )
 endif

@@ -1,4 +1,5 @@
-# Migrating from GTK 2.x to GTK 4 {#gtk-migrating-2-to-4}
+Title: Migrating from GTK 2.x to GTK 4
+Slug: gtk-migrating-2-to-4

 If your application is still using GTK 2, you should first convert it to GTK 3,
 by following the [migration guide](https://developer.gnome.org/gtk3/stable/gtk-migrating-2-to-3.html)
@@ -1,4 +1,5 @@
-# Migrating from GTK 3.x to GTK 4 {#gtk-migrating-3-to-4}
+Title: Migrating from GTK 3.x to GTK 4
+Slug: gtk-migrating-3-to-4

 GTK 4 is a major new version of GTK that breaks both API and ABI
 compared to GTK 3.x. Thankfully, most of the changes are not hard
@@ -28,6 +29,7 @@ of all deprecated symbols.
 To verify that your program does not use any deprecated symbols,
 you can use defines to remove deprecated symbols from the header files,
 as follows:
+
 ```
 make CFLAGS+="-DGDK_DISABLE_DEPRECATED -DGTK_DISABLE_DEPRECATED"
 ```
@@ -45,6 +47,7 @@ types have been instantiated. In order to catch deprecations and
 changes in the run time components, you should use the
 `G_ENABLE_DIAGNOSTIC` environment variable when running your
 application, e.g.:
+
 ```
 G_ENABLE_DIAGNOSTIC=1 ./your-app
 ```
@@ -66,12 +69,12 @@ your custom CSS and in your code.
 ### Review your window creation flags

 GTK 4 removes the `GDK_WA_CURSOR` flag. Instead, just use
-gdk_window_set_cursor() to set a cursor on the window after
+`gdk_window_set_cursor()` to set a cursor on the window after
 creating it. GTK 4 also removes the `GDK_WA_VISUAL` flag, and
 always uses an RGBA visual for windows. To prepare your code for
 this, use `gdk_window_set_visual (gdk_screen_get_rgba_visual ())`
 after creating your window. GTK 4 also removes the `GDK_WA_WMCLASS`
-flag. If you need this X11-specific functionality, use XSetClassHint()
+flag. If you need this X11-specific functionality, use `XSetClassHint()`
 directly.

 ### Stop using direct access to GdkEvent structs
@@ -80,71 +83,72 @@ In GTK 4, event structs are opaque and immutable. Many fields already
 have accessors in GTK 3, and you should use those to reduce the amount
 of porting work you have to do at the time of the switch.

-### Stop using gdk_pointer_warp()
+### Stop using `gdk_pointer_warp()`

 Warping the pointer is disorienting and unfriendly to users.
 GTK 4 does not support it. In special circumstances (such as when
 implementing remote connection UIs) it can be necessary to
 warp the pointer; in this case, use platform APIs such as
-XWarpPointer() directly.
+`XWarpPointer()` directly.

 ### Stop using non-RGBA visuals

 GTK 4 always uses RGBA visuals for its windows; you should make
 sure that your code works with such visuals. At the same time,
-you should stop using GdkVisual APIs, since this object not longer
+you should stop using `GdkVisual` APIs, since this object not longer
 exists in GTK 4. Most of its APIs are deprecated already and not
 useful when dealing with RGBA visuals.

-### Stop using GtkBox padding, fill and expand child properties
+### Stop using `GtkBox` padding, fill and expand child properties

-GTK 4 removes these #GtkBox child properties, so you should stop using
-them. You can replace GtkBox:padding using the #GtkWidget:margin properties
-on your #GtkBox child widgets.
+GTK 4 removes these [class@Gtk.Box] child properties, so you should stop using
+them. You can replace `GtkBox:padding` using `GtkWidget`'s `margin-*` properties
+on your [class@Gtk.Box] child widgets.

-The fill child property can be replaced by setting appropriate values
-for the #GtkWidget:halign and #GtkWidget:valign properties of the child
-widgets. If you previously set the fill child property to %TRUE, you can
-achieve the same effect by setting the halign or valign properties to
-%GTK_ALIGN_FILL, depending on the parent box -- halign for a horizontal
-box, valign for a vertical one.
+The fill child property can be replaced by setting appropriate values for
+the [property@Gtk.Widget:halign] and [property@Gtk.Widget:valign] properties
+of the child widgets. If you previously set the `fill` child property to
+`TRUE`, you can achieve the same effect by setting the `halign` or `valign`
+properties to `GTK_ALIGN_FILL`, depending on the parent box -- `halign` for a
+horizontal box, `valign` for a vertical one.

-\#GtkBox also uses the expand child property. It can be replaced by setting
-#GtkWidget:hexpand or #GtkWidget:vexpand on the child widgets. To match the
-old behavior of the #GtkBox's expand child property, you need to set
-#GtkWidget:hexpand on the child widgets of a horizontal #GtkBox and
-#GtkWidget:vexpand on the child widgets of a vertical #GtkBox.
+[class@Gtk.Box] also uses the expand child property. It can be replaced by
+setting [property@Gtk.Widget:hexpand] or [property@Gtk.Widget:vexpand] on
+the child widgets. To match the old behavior of the #GtkBox's expand child
+property, you need to set `hexpand` on the child widgets of a horizontal
+`GtkBox` and `vexpand` on the child widgets of a vertical `GtkBox`.

-Note that there's a subtle but important difference between #GtkBox's
-expand and fill child properties and the ones in #GtkWidget: setting
-#GtkWidget:hexpand or #GtkWidget:vexpand to %TRUE will propagate up
-the widget hierarchy, so a pixel-perfect port might require you to reset
-the expansion flags to %FALSE in a parent widget higher up the hierarchy.
+Note that there's a subtle but important difference between `GtkBox`'s
+`expand` and `fill` child properties and the ones in `GtkWidget`: setting
+[property@Gtk.Widget:hexpand] or [property@Gtk.Widget:vexpand] to `TRUE`
+will propagate up the widget hierarchy, so a pixel-perfect port might
+require you to reset the expansion flags to `FALSE` in a parent widget higher
+up the hierarchy.

-### Stop using the state argument of GtkStyleContext getters
+### Stop using the state argument of `GtkStyleContext` getters

-The getters in the GtkStyleContext API, such as
-gtk_style_context_get_property(), gtk_style_context_get(),
-or gtk_style_context_get_color() only accept the context's current
+The getters in the [class@Gtk.StyleContext] API, such as
+`gtk_style_context_get_property()`, `gtk_style_context_get()`,
+or `gtk_style_context_get_color()` only accept the context's current
 state for their state argument. You should update all callers to pass
 the current state.

-### Stop using gdk_pixbuf_get_from_window() and gdk_cairo_set_source_surface()
+### Stop using `gdk_pixbuf_get_from_window()` and `gdk_cairo_set_source_surface()`

 These functions are not supported in GTK 4. Instead, either use
 backend-specific APIs, or render your widgets using
-#GtkWidgetClass.snapshot() (once you are using GTK 4).
+[vfunc@Gtk.Widget.snapshot], once you are using GTK 4.

-### Stop using GtkButton's image-related API
+### Stop using `GtkButton`'s image-related API

-The functions and properties related to automatically add a GtkImage
-to a GtkButton, and using a GtkSetting to control its visibility, are
-not supported in GTK 4. Instead, you can just pack a GtkImage inside
-a GtkButton, and control its visibility like you would for any other
-widget. If you only want to add a named icon to a GtkButton, you can
-use gtk_button_new_from_icon_name().
+The functions and properties related to automatically add a
+[class@Gtk.Image] to a [class@Gtk.Button], and using a `GtkSetting` to
+control its visibility, are not supported in GTK 4. Instead, you can just
+pack a GtkImage inside a GtkButton, and control its visibility like you
+would for any other widget. If you only want to add a named icon to a
+GtkButton, you can use [`ctor@Gtk.Button.new_from_icon_name`].

-### Stop using GtkWidget event signals
+### Stop using `GtkWidget` event signals

 Event controllers and gestures replace event signals in GTK 4.

@@ -182,59 +186,60 @@ for this change.
 | ::damage-event | - |
 | ::grab-broken-event | - |

-Event signals which are not directly related to input have to be dealt
-with on a one-by-one basis. If you were using ::configure-event and
-::window-state-event to save window state, you should use property
-notification for corresponding GtkWindow properties, such as
-#GtkWindow:default-width, #GtkWindow:default-height, #GtkWindow:maximized
-or #GtkWindow:fullscreened.
+Event signals which are not directly related to input have to be dealt with
+on a one-by-one basis. If you were using `::configure-event` and
+`::window-state-event` to save window state, you should use property
+notification for corresponding [class@Gtk.Window] properties, such as
+[property@Gtk.Window:default-width], [property@Gtk.Window:default-height],
+[property@Gtk.Window:maximized] or [property@Gtk.Window:fullscreened].

 ### Set a proper application ID

-In GTK 4 we want the application's #GApplication 'application-id'
-(and therefore the D-Bus name), the desktop file basename and Wayland's
-xdg-shell app_id to match. In order to achieve this with GTK 3.x call
-g_set_prgname() with the same application ID you passed to #GtkApplication.
-Rename your desktop files to match the application ID if needed.
+In GTK 4 we want the application's `GApplication` 'application-id' (and
+therefore the D-Bus name), the desktop file basename and Wayland's xdg-shell
+`app_id` to match. In order to achieve this with GTK 3.x call
+`g_set_prgname()` with the same application ID you passed to
+[class@Gtk.Application].  Rename your desktop files to match the application
+ID if needed.

-The call to g_set_prgname() can be removed once you fully migrated to GTK 4.
+The call to `g_set_prgname()` can be removed once you fully migrated to GTK 4.

 You should be aware that changing the application ID makes your
 application appear as a new, different app to application installers.
 You should consult the appstream documentation for best practices
 around renaming applications.

-### Stop using gtk_main() and related APIs
+### Stop using `gtk_main()` and related APIs

-GTK 4 removes the gtk_main_ family of APIs. The recommended replacement
-is GtkApplication, but you can also iterate the GLib mainloop directly,
-using GMainContext APIs. The replacement for gtk_events_pending() is
-g_main_context_pending(), the replacement for gtk_main_iteration() is
-g_main_context_iteration().
+GTK 4 removes the `gtk_main_*` family of APIs. The recommended replacement
+is [class@Gtk.Application], but you can also iterate the GLib main loop directly,
+using `GMainContext` APIs. The replacement for `gtk_events_pending()` is
+`g_main_context_pending()`, the replacement for `gtk_main_iteration()` is
+`g_main_context_iteration()`.

-### Reduce the use of gtk_widget_destroy()
+### Reduce the use of `gtk_widget_destroy()`

-GTK 4 introduces a gtk_window_destroy() api. While that is not available
-in GTK 3, you can prepare for the switch by using gtk_widget_destroy()
+GTK 4 introduces a [method@Gtk.Window.destroy] api. While that is not available
+in GTK 3, you can prepare for the switch by using `gtk_widget_destroy()`
 only on toplevel windows, and replace all other uses with
-gtk_container_remove() or g_object_unref().
+`gtk_container_remove()` or `g_object_unref()`.

 ### Reduce the use of generic container APIs

-GTK 4 removes gtk_container_add() and gtk_container_remove(). While there
-is not always a replacement for gtk_container_remove() in GTK 3, you can
-replace many uses of gtk_container_add() with equivalent container-specific
-APIs such as gtk_box_pack_start() or gtk_grid_attach(), and thereby reduce
+GTK 4 removes `gtk_container_add()` and `gtk_container_remove()`. While there
+is not always a replacement for `gtk_container_remove()` in GTK 3, you can
+replace many uses of `gtk_container_add()` with equivalent container-specific
+APIs such as `gtk_box_pack_start()` or `gtk_grid_attach()`, and thereby reduce
 the amount of work you have to do at the time of the switch.

 ### Review your use of icon resources

 When using icons as resources, the behavior of GTK 4 is different in one
-respect: Icons that are directly in $APP_ID/icons/ are treated as unthemed
+respect: Icons that are directly in `$APP_ID/icons/` are treated as unthemed
 icons, which also means that symbolic icons are not recolored. If you want
 your icon resources to have icon theme semantics, they need to be placed
-into theme subdirectories such as $APP_ID/icons/16x16/actions or
-$APP_ID/icons/scalable/status.
+into theme subdirectories such as `$APP_ID/icons/16x16/actions` or
+`$APP_ID/icons/scalable/status`.

 This location works fine in GTK 3 too, so you can prepare for this change
 before switching to GTK 4.
@@ -262,52 +267,52 @@ and use complex widgets as child widgets instead of deriving from them.

 Widgets in GTK 4 are treated like any other objects - their parent widget
 holds a reference on them, and GTK holds a reference on toplevel windows.
-gtk_window_destroy() will drop the reference on the toplevel window, and
-cause the whole widget hierarchy to be finalized unless there are other
+[method@Gtk.Window.destroy] will drop the reference on the toplevel window,
+and cause the whole widget hierarchy to be finalized unless there are other
 references that keep widgets alive.

-The #GtkWidget::destroy signal is emitted when a widget is disposed, and
-therefore can no longer be used to break reference cycles. A typical sign
-of a reference cycle involving a toplevel window is when closing the window
-does not make the application quit.
+The [signals@Gtk.Widget::destroy] signal is emitted when a widget is
+disposed, and therefore can no longer be used to break reference cycles. A
+typical sign of a reference cycle involving a toplevel window is when
+closing the window does not make the application quit.

 ### Stop using GdkScreen

-The GdkScreen object has been removed in GTK 4. Most of its APIs already
+The `GdkScreen` object has been removed in GTK 4. Most of its APIs already
 had replacements in GTK 3 and were deprecated, a few remaining replacements
-have been added to GdkDisplay.
+have been added to `GdkDisplay`.

 ### Stop using the root window

 The root window is an X11-centric concept that is no longer exposed in the
 backend-neutral GDK API. If you need to interact with the X11 root window,
-you can use gdk_x11_display_get_xrootwindow() to get its XID.
+you can use `gdk_x11_display_get_xrootwindow()` to get its XID.

-### Stop using GdkVisual
+### Stop using `GdkVisual`

 This object is not useful with current GTK drawing APIs and has been removed
 without replacement.

-### Stop using GdkDeviceManager
+### Stop using `GdkDeviceManager`

 The GdkDeviceManager object has been removed in GTK 4. Most of its APIs already
-had replacements in GTK 3 and were deprecated in favor of GdkSeat.
+had replacements in GTK 3 and were deprecated in favor of `GdkSeat`.

-### Adapt to GdkWindow API changes
+### Adapt to `GdkWindow` API changes

-GdkWindow has been renamed to GdkSurface.
+`GdkWindow` has been renamed to `GdkSurface`.

-In GTK 4, the two roles of a standalone toplevel window and of a popup
-that is placed relative to a parent window have been separated out into
-two interfaces, #GdkToplevel and #GdkPopup. Surfaces implementing these
-interfaces are created with gdk_surface_new_toplevel() and
-gdk_surface_new_popup(), respectively, and they are presented on screen
-using gdk_toplevel_present() and gdk_popup_present(). The present()
-functions take parameters in the form of an auxiliary layout struct,
-#GdkPopupLayout or #GdkToplevelLayout. If your code is dealing directly
-with surfaces, you may have to change it to call the API in these
-interfaces, depending on whether the surface you are dealing with
-is a toplevel or a popup.
+In GTK 4, the two roles of a standalone toplevel window and of a popup that
+is placed relative to a parent window have been separated out into two
+interfaces, [class@Gdk.Toplevel] and [class@Gdk.Popup]. Surfaces
+implementing these interfaces are created with `gdk_surface_new_toplevel()`
+and `gdk_surface_new_popup()`, respectively, and they are presented on
+screen using `gdk_toplevel_present()` and `gdk_popup_present()`. The
+`present()` functions take parameters in the form of an auxiliary layout
+struct, [struct@Gdk.PopupLayout] or [struct@Gdk.ToplevelLayout]. If your
+code is dealing directly with surfaces, you may have to change it to call
+the API in these interfaces, depending on whether the surface you are
+dealing with is a toplevel or a popup.

 As part of this reorganization, X11-only concepts such as sticky,
 keep-below, urgency, skip-taskbar or window groups have either been
@@ -316,95 +321,95 @@ X11 windows, you will have to use those backend apis or set the
 corresponding X11 properties (as specified in the EWMH) yourself.

 Subsurfaces are only supported with the Wayland backend, using
-gdk_wayland_surface_new_subsurface(). Native and foreign subwindows
+`gdk_wayland_surface_new_subsurface()`. Native and foreign subwindows
 are no longer supported. These concepts were complicating the code
 and could not be supported across backends.

 A number of GdkWindow APIs are no longer available. This includes
-gdk_window_reparent(), gdk_window_set_geometry_hints(), gdk_window_raise(),
-gdk_window_restack(), gdk_window_move(), gdk_window_resize(). If
+`gdk_window_reparent()`, `gdk_window_set_geometry_hints()`, `gdk_window_raise()`,
+`gdk_window_restack()`, `gdk_window_move()`, `gdk_window_resize()`. If
 you need to manually control the position or stacking of your X11
 windows, you you will have to use Xlib apis.

-A number of minor API cleanups have happened in GdkSurface
-as well. For example, gdk_surface_input_shape_combine_region()
-has been renamed to gdk_surface_set_input_region(), and
-gdk_surface_begin_resize_drag() has been renamed to
-gdk_toplevel_begin_resize().
+A number of minor API cleanups have happened in `GdkSurface`
+as well. For example, `gdk_surface_input_shape_combine_region()`
+has been renamed to `gdk_surface_set_input_region()`, and
+`gdk_surface_begin_resize_drag()` has been renamed to
+`gdk_toplevel_begin_resize()`.

 ### The "iconified" window state has been renamed to "minimized"

-The %GDK_TOPLEVEL_STATE_ICONIFIED value of the #GdkSurfaceState enumeration
-is now %GDK_TOPLEVEL_STATE_MINIMIZED in the #GdkToplevelState enumeration.
+The `GDK_TOPLEVEL_STATE_ICONIFIED` value of the `GdkSurfaceState` enumeration
+is now `GDK_TOPLEVEL_STATE_MINIMIZED` in the `GdkToplevelState` enumeration.

-The #GdkWindow functions gdk_window_iconify() and gdk_window_deiconify()
-have been renamed to gdk_toplevel_minimize() and gdk_toplevel_present(),
-respectively.
+The `GdkWindow` functions `gdk_window_iconify()` and
+`gdk_window_deiconify()` have been renamed to `gdk_toplevel_minimize()` and
+`gdk_toplevel_present()`, respectively.

 The behavior of the minimization and unminimization operations have
 not been changed, and they still require support from the underlying
 windowing system.

-### Adapt to GdkEvent API changes
+### Adapt to `GdkEvent` API changes

-Direct access to GdkEvent structs is no longer possible in GTK 4.
+Direct access to [class@Gdk.Event] structs is no longer possible in GTK 4.
 GdkEvent is now a strictly read-only type, and you can no longer
 change any of its fields, or construct new events. All event fields
 have accessors that you will have to use.

 Event compression is always enabled in GTK 4, for both motion and
 scroll events. If you need to see the uncoalesced motion or scroll
-history, use gdk_event_get_history() on the latest event.
+history, use `gdk_event_get_history()` on the latest event.

 ### Stop using grabs

-GTK 4 no longer provides the gdk_device_grab() or gdk_seat_grab()
+GTK 4 no longer provides the `gdk_device_grab()` or `gdk_seat_grab()`
 apis. If you need to dismiss a popup when the user clicks outside
-(the most common use for grabs), you can use the GdkPopup
-#GdkPopup:autohide property instead. GtkPopover also has a
-#GtkPopover:autohide property for this. If you need to prevent
+(the most common use for grabs), you can use the `GdkPopup`
+`GdkPopup:autohide` property instead. [class@Gtk.Popover] also has a
+`GtkPopover:autohide` property for this. If you need to prevent
 the user from interacting with a window while a dialog is open,
-use the #GtkWindow:modal property of the dialog.
+use the [property@Gtk.Window:modal] property of the dialog.

 ### Adapt to coordinate API changes

-A number of coordinate APIs in GTK 3 had _double variants: 
-gdk_device_get_surface_at_position(), gdk_surface_get_device_position().
-These have been changed to use doubles, and the _double variants
+A number of coordinate APIs in GTK 3 had `double` variants: 
+`gdk_device_get_surface_at_position()`, `gdk_surface_get_device_position()`.
+These have been changed to use doubles, and the `double` variants
 have been removed. Update your code accordingly.

 Any APIs that deal with global (or root) coordinates have been
 removed in GTK 4, since not all backends support them. You should
 replace your use of such APIs with surface-relative equivalents.
-Examples of this are gdk_surface_get_origin(), gdk_surface_move()
-or gdk_event_get_root_coords().
+Examples of this are `gdk_surface_get_origin()`, `gdk_surface_move()`
+or `gdk_event_get_root_coords()`.

-### Adapt to GdkKeymap API changes
+### Adapt to `GdkKeymap` API changes

-GdkKeymap no longer exists as an independent object.
+`GdkKeymap` no longer exists as an independent object.

 If you need access to keymap state, it is now exposed as properties
-on the #GdkDevice representing the keyboard: #GdkDevice:direction,
-#GdkDevice:has-bidi-layouts, #GdkDevice:caps-lock-state,
-#GdkDevice:num-lock-state, #GdkDevice:scroll-lock-state and
-#GdkDevice:modifier-state. To obtain the keyboard device, you can use
+on the `GdkDevice` representing the keyboard: `GdkDevice:direction`,
+`GdkDevice:has-bidi-layouts`, `GdkDevice:caps-lock-state`,
+`GdkDevice:num-lock-state`, `GdkDevice:scroll-lock-state` and
+`GdkDevice:modifier-state`. To obtain the keyboard device, you can use
 `gdk_seat_get_keyboard (gdk_display_get_default_seat (display)`.

-If you need access to translated keys for event handling, #GdkEvent
+If you need access to translated keys for event handling, `GdkEvent`
 now includes all of the translated key state, including consumed
 modifiers, group and shift level, so there should be no need to
-manually call gdk_keymap_translate_keyboard_state() (which has
+manually call `gdk_keymap_translate_keyboard_state()` (which has
 been removed).

 If you need to do forward or backward mapping between key codes
-and key values, use gdk_display_map_keycode() and gdk_display_map_keyval(),
-which are the replacements for gdk_keymap_get_entries_for_keycode()
-and gdk_keymap_get_entries_for_keyval().
+and key values, use `gdk_display_map_keycode()` and `gdk_display_map_keyval()`,
+which are the replacements for `gdk_keymap_get_entries_for_keycode()`
+and `gdk_keymap_get_entries_for_keyval()`.

 ### Adapt to changes in keyboard modifier handling

 GTK 3 has the idea that use of modifiers may differ between different
-platforms, and has a #GdkModifierIntent api to let platforms provide
+platforms, and has a `GdkModifierIntent` api to let platforms provide
 hint about how modifiers are expected to be used. It also promoted
 the use of `<Primary>` instead of `<Control>` to specify accelerators that
 adapt to platform conventions.
@@ -413,36 +418,40 @@ In GTK 4, the meaning of modifiers has been fixed, and backends are
 expected to map the platform conventions to the existing modifiers.
 The expected use of modifiers in GTK 4 is:

-GDK_CONTROL_MASK
+`GDK_CONTROL_MASK`
 : Primary accelerators
- GDK_ALT_MASK
+
+`GDK_ALT_MASK`
 :  Mnemonics
-GDK_SHIFT_MASK
+
+`GDK_SHIFT_MASK`
 : Extending selections
-GDK_CONTROL_MASK
+
+`GDK_CONTROL_MASK`
 : Modifying selections
-GDK_CONTROL_MASK|GDK_ALT_MASK
+
+`GDK_CONTROL_MASK|GDK_ALT_MASK`
 : Prevent text input

-Consequently, #GdkModifierIntent and related APIs have been removed,
+Consequently, `GdkModifierIntent` and related APIs have been removed,
 and `<Control>` is preferred over `<Primary>` in accelerators.

 A related change is that GTK 4 no longer supports the use of archaic
-X11 'real' modifiers with the names Mod1,..., Mod5, and %GDK_MOD1_MASK
-has been renamed to %GDK_ALT_MASK.
+X11 'real' modifiers with the names Mod1,..., Mod5, and `GDK_MOD1_MASK`
+has been renamed to `GDK_ALT_MASK`.

-### Replace GtkClipboard with GdkClipboard
+### Replace `GtkClipboard` with `GdkClipboard`

-The `GtkClipboard` API has been removed, and replaced by #GdkClipboard.
+The `GtkClipboard` API has been removed, and replaced by `GdkClipboard`.
 There is not direct 1:1 mapping between the old an the new API, so it cannot
-be a mechanical replacement; the new API is based on object types and #GValue
+be a mechanical replacement; the new API is based on object types and `GValue`
 like object properties, instead of opaque identifiers, so it should be easier
 to use.

 For instance, the example below copies the contents of an entry into the
 clipboard:

-```
+```c
 static void
 copy_text (GtkWidget *widget)
 {
@@ -463,7 +472,7 @@ copy_text (GtkWidget *widget)

 whereas the example below pastes the contents into the entry:

-```
+```c
 static void
 paste_text (GtkWidget *widget)
 {
@@ -492,7 +501,7 @@ paste_text (GtkWidget *widget)
 The convenience API for specific target types in `GtkClipboard` has been
 replaced by their corresponding GType:

-| GtkClipboard                         | GType                 |
+| GtkClipboard                        | GType                  |
 | ----------------------------------- | ---------------------- |
 | `gtk_clipboard_request_text()`      | `G_TYPE_STRING`        |
 | `gtk_clipboard_request_rich_text()` | `GTK_TYPE_TEXT_BUFFER` |
@@ -503,174 +512,179 @@ replaced by their corresponding GType:
 for #GtkTextBuffer is not available any more.

 If you are copying the contents of an image, it is recommended to use
-GDK_TYPE_PAINTABLE instead of GDK_TYPE_PIXBUF, to minimize the amount of
+`GDK_TYPE_PAINTABLE` instead of `GDK_TYPE_PIXBUF`, to minimize the amount of
 potential copies.

 ### Stop using `gtk_get_current_...` APIs

-The function gtk_get_current_event() and its variants have been
+The function `gtk_get_current_event()` and its variants have been
 replaced by equivalent event controller APIs:
-gtk_event_controller_get_current_event(), etc.
+`gtk_event_controller_get_current_event()`, etc.

-### Convert your ui files
+### Convert your UI files

-A number of the changes outlined below affect .ui files. The
-gtk4-builder-tool simplify command can perform many of the
-necessary changes automatically, when called with the --3to4
+A number of the changes outlined below affect `.ui` files. The
+`gtk4-builder-tool simplify` command can perform many of the
+necessary changes automatically, when called with the `--3to4`
 option. You should always review the resulting changes.

-The <requires> tag now supports for the 'lib' attribute the
-'gtk' value only, instead of the 'gtk+' one previously.
+The `<requires>` tag now supports for the `lib` attribute the
+`gtk` value only, instead of the `gtk+` one previously.

 ### Adapt to GtkBuilder API changes

-gtk_builder_connect_signals() no longer exists. Instead, signals are
+`gtk_builder_connect_signals()` no longer exists. Instead, signals are
 always connected automatically. If you need to add user data to your
-signals, gtk_builder_set_current_object() must be called. An important
+signals, `gtk_builder_set_current_object()` must be called. An important
 caveat is that you have to do this before loading any XML. This means if
-you need to use gtk_builder_set_current_object(), you can no longer use
-gtk_builder_new_from_file(), gtk_builder_new_from_resource(), or
-gtk_builder_new_from_string(). Instead, you must use vanilla gtk_builder_new(),
-then call gtk_builder_set_current_object(), then load the XML using
-gtk_builder_add_from_file(), gtk_builder_add_from_resource(), or
-gtk_builder_add_from_string(). You must check the return value for
-failure and manually abort with g_error() if something went wrong.
+you need to use `gtk_builder_set_current_object()`, you can no longer use
+`gtk_builder_new_from_file()`, `gtk_builder_new_from_resource()`, or
+`gtk_builder_new_from_string()`. Instead, you must use vanilla `gtk_builder_new()`,
+then call `gtk_builder_set_current_object()`, then load the XML using
+`gtk_builder_add_from_file()`, `gtk_builder_add_from_resource()`, or
+`gtk_builder_add_from_string()`. You must check the return value for
+failure and manually abort with `g_error()` if something went wrong.

 You only have to worry about this if you were previously using
-gtk_builder_connect_signals(). If you are using templates, then
-gtk_widget_init_template() will call gtk_builder_set_current_object()
+`gtk_builder_connect_signals()`. If you are using templates, then
+`gtk_widget_init_template()` will call `gtk_builder_set_current_object()`
 for you, so templates work like before.

 ### Adapt to event controller API changes

-A few changes to the event controller and #GtkGesture APIs
+A few changes to the event controller and [class@Gtk.Gesture] APIs
 did not make it back to GTK 3, and have to be taken into account
-when moving to GTK 4. One is that the #GtkEventControllerMotion::enter
-and #GtkEventControllerMotion::leave signals have gained new arguments.
-Another is that #GtkGestureMultiPress has been renamed to #GtkGestureClick,
-and has lost its area property. A #GtkEventControllerFocus has been
-split off from #GtkEventcontrollerKey.
+when moving to GTK 4. One is that the [signal@Gtk.EventControllerMotion::enter]
+and [signals@Gtk.EventControllerMotion::leave] signals have gained new arguments.
+Another is that `GtkGestureMultiPress` has been renamed to [class@Gtk.GestureClick],
+and has lost its area property. A [class@Gtk.EventControllerFocus] has been
+split off from [class@Gtk.EventControllerKey].

-In GTK 3, #GtkEventController:widget was a construct-only property, so
-a #GtkWidget was provided whenever constructing a #GtkEventController.
-In GTK 4, #GtkEventController:widget is now read-only. Use
-gtk_widget_add_controller() to add an event controller to a widget.
+In GTK 3, `GtkEventController:widget` was a construct-only property, so a
+`GtkWidget` was provided whenever constructing a `GtkEventController`.  In
+GTK 4, [property@Gtk.EventController:widget] is now read-only. Use
+[`method@Gtk.Widget.add_controller`] to add an event controller to a widget.

 In GTK 3, widgets did not own their event controllers, and event
 controllers did not own their widgets, so developers were responsible
 for manually keeping event controllers alive for the lifetime of their
 associated widgets. In GTK 4, widgets own their event controllers.
-gtk_widget_add_controller() takes ownership of the event controller, so
+[`method@Gtk.Widget.add_controller`] takes ownership of the event controller, so
 there is no longer any need to store a reference to the event controller
 after it has been added to a widget.

 Although not normally needed, an event controller could be removed from
-a widget in GTK 3 by destroying the event controller with g_object_unref().
-In GTK 4, you must use gtk_widget_remove_controller().
+a widget in GTK 3 by destroying the event controller with `g_object_unref()`.
+In GTK 4, you must use [`method@Gtk.Widget.remove_controller()`].

 ### Focus handling changes

-The semantics of the #GtkWidget:can-focus property have changed.
+The semantics of the [property@Gtk.Widget:can-focus] property have changed.
 In GTK 3, this property only meant that the widget itself would not
 accept keyboard input, but its children still might (in the case of
-containers). In GTK 4, if :can-focus is %FALSE, the focus cannot enter
+containers). In GTK 4, if `:can-focus` is `FALSE`, the focus cannot enter
 the widget or any of its descendents, and the default value has changed
-from %FALSE to %TRUE. In addition, there is a #GtkWidget:focusable
+from `FALSE` to `TRUE`. In addition, there is a [property@Gtk.Widget:focusable]
 property, which controls whether an individual widget can receive
 the input focus.

-The feature to automatically keep the focus widget scrolled into view
-with gtk_container_set_focus_vadjustment() has been removed together with
-GtkContainer, and is provided by scrollable widgets instead. In the common
-case that the scrollable is a #GtkViewport, use #GtkViewport:scroll-to-focus.
+The feature to automatically keep the focus widget scrolled into view with
+`gtk_container_set_focus_vadjustment()` has been removed together with
+`GtkContainer`, and is provided by scrollable widgets instead. In the common
+case that the scrollable is a [class@Gtk.Viewport], use
+[property@Gtk.Viewport:scroll-to-focus].

 ### Use the new apis for keyboard shortcuts

 The APIs for keyboard shortcuts and accelerators have changed in GTK 4.

-Instead of GtkAccelGroup, you now use a #GtkShortcutController with global
-scope, and instead of GtkBindingSet, you now use gtk_widget_class_add_shortcut(),
-gtk_widget_class_add_binding() and its variants. In both cases, you probably
+Instead of `GtkAccelGroup`, you now use a [class@Gtk.ShortcutController] with global
+scope, and instead of `GtkBindingSet`, you now use `gtk_widget_class_add_shortcut()`,
+`gtk_widget_class_add_binding()` and its variants. In both cases, you probably
 want to add actions that can be triggered by your shortcuts.

 There is no direct replacement for loading and saving accelerators with
-GtkAccelMap. But since #GtkShortcutController implements #GListModel and
-both #GtkShortcutTrigger and #GtkShortcutAction can be serialized to
-strings, it is relatively easy to implement saving and loading yourself. 
+`GtkAccelMap`. But since `GtkShortcutController` implements `GListModel` and
+both [class@Gtk.ShortcutTrigger] and [class@Gtk.ShortcutAction] can be
+serialized to strings, it is relatively easy to implement saving and loading
+yourself. 

-### Stop using GtkEventBox
+### Stop using `GtkEventBox`
+
+`GtkEventBox` is no longer needed and has been removed.

-GtkEventBox is no longer needed and has been removed.
 All widgets receive all events.

-### Stop using GtkButtonBox
+### Stop using `GtkButtonBox`

-GtkButtonBox has been removed. Use a GtkBox instead.
+`GtkButtonBox` has been removed. Use a [class@Gtk.Box] instead.

-### Adapt to GtkBox API changes
+### Adapt to `GtkBox` API changes

-The GtkBox pack-start and -end methods have been replaced by gtk_box_prepend()
-and gtk_box_append(). You can also reorder box children as necessary.
+The GtkBox `pack_start()` and `pack_end()` methods have been replaced by
+[method@Gtk.Box.prepend] and [method@Gtk.Box.append]. You can also reorder
+box children as necessary.

-### Adapt to GtkWindow API changes
+### Adapt to `GtkWindow` API changes

-Following the GdkSurface changes, a number of GtkWindow APIs that were
-X11-specific have been removed. This includes gtk_window_set_geometry_hints(),
-gtk_window_set_gravity(), gtk_window_move(), gtk_window_parse_geometry(),
-gtk_window_set_keep_above(), gtk_window_set_keep_below(),
-gtk_window_begin_resize_drag(), gtk_window_begin_move_drag().
+Following the `GdkSurface` changes, a number of `GtkWindow` APIs that were
+X11-specific have been removed. This includes `gtk_window_set_geometry_hints()`,
+`gtk_window_set_gravity()`, `gtk_window_move()`, `gtk_window_parse_geometry()`,
+`gtk_window_set_keep_above()`, `gtk_window_set_keep_below()`,
+`gtk_window_begin_resize_drag()`, `gtk_window_begin_move_drag()`.
 Most likely, you should just stop using them. In some cases, you can
-fall back to using the underlying #GdkToplevel APIs (for example,
-gdk_toplevel_begin_resize()).
+fall back to using the underlying `GdkToplevel` APIs (for example,
+`gdk_toplevel_begin_resize()`).

-The APIs for controlling GtkWindow size have changed to be better aligned
-with the way size changes are integrated in the frame cycle. gtk_window_resize()
-and gtk_window_get_size() have been removed. Instead, use
-gtk_window_set_default_size() and gtk_window_get_default_size().
+The APIs for controlling `GtkWindow` size have changed to be better aligned
+with the way size changes are integrated in the frame cycle. `gtk_window_resize()`
+and `gtk_window_get_size()` have been removed. Instead, use
+`gtk_window_set_default_size()` and `gtk_window_get_default_size()`.

-### Adapt to GtkHeaderBar and GtkActionBar API changes
+### Adapt to `GtkHeaderBar` and `GtkActionBar` API changes

-The gtk_header_bar_set_show_close_button() function has been renamed to
-the more accurate name gtk_header_bar_set_show_title_buttons(). The
+The `gtk_header_bar_set_show_close_button()` function has been renamed to
+the more accurate name [`method@Gtk.HeaderBar.set_show_title_buttons`]. The
 corresponding getter and the property itself have also been renamed.
- The default value of the property is now %TRUE instead of %FALSE.
+The default value of the property is now `TRUE` instead of `FALSE`.

-The gtk_header_bar_set_custom_title() function has been renamed to
-the more accurate name gtk_header_bar_set_title_widget(). The
+The `gtk_header_bar_set_custom_title()` function has been renamed to
+the more accurate name [`method@Gtk.HeaderBar.set_title_widget`]. The
 corresponding getter and the property itself have also been renamed.

-The gtk_header_bar_set_title() function has been removed along with its
-corresponding getter and the property. By default #GtkHeaderBar shows
-the title of the window, so if you were setting the title of the header
-bar, consider setting the window title instead. If you need to show a
+The `gtk_header_bar_set_title()` function has been removed along with its
+corresponding getter and the property. By default [class@Gtk.HeaderBar]
+shows the title of the window, so if you were setting the title of the
+header bar, consider setting the window title instead. If you need to show a
 title that's different from the window title, use the
-#GtkHeaderBar:title-widget property to add a #GtkLabel as shown in the
-example in the #GtkHeaderBar documentation.
+[property@Gtk.HeaderBar:title-widget] property to add a [class@Gtk.Label] as
+shown in the example in the [class@Gtk.HeaderBar] documentation.

-The gtk_header_bar_set_subtitle() function has been removed along with
+The `gtk_header_bar_set_subtitle()` function has been removed along with
 its corresponding getter and the property. The old "subtitle" behavior
-can be replicated by setting the #GtkHeaderBar:title-widget property to
-a #GtkBox with two labels inside, with the title label matching the
-example in #GtkHeaderBar documentation, and the subtitle label being
-similar, but with "subtitle" style class instead of "title".
+can be replicated by setting the [property@Gtk.HeaderBar:title-widget] property to
+a [class@Gtk.Box] with two labels inside, with the title label matching the
+example in `GtkHeaderBar` documentation, and the subtitle label being
+similar, but with `"subtitle"` style class instead of `"title"`.

-The gtk_header_bar_set_has_subtitle() function has been removed along
-with its corresponding getter and the property. Its behavior can be
-replicated by setting the #GtkHeaderBar:title-widget property to a
-#GtkStack with #GtkStack:vhomogeneous property set to %TRUE and two
-pages, each with a #GtkBox with title and subtitle as described above.
+The `gtk_header_bar_set_has_subtitle()` function has been removed along with
+its corresponding getter and the property. Its behavior can be replicated by
+setting the [property@Gtk.HeaderBar:title-widget] property to a
+[class@Gtk.Stack] with [property@Gtk.Stack:vhomogeneous] property set to
+`TRUE` and two pages, each with a [class@Gtk.Box] with title and subtitle as
+described above.

-Some of the internal structure of #GtkHeaderBar has been made available
-as public API: #GtkWindowHandle and #GtkWindowControls. If you have
-unusual needs for custom headerbars, these might be useful to you.
+Some of the internal structure of `GtkHeaderBar` has been made available as
+public API: [class@Gtk.WindowHandle] and [class@Gtk.WindowControls]. If you
+have unusual needs for custom headerbars, these might be useful to you.

-The ::pack-type child properties of GtkHeaderBar and GtkActionBar have
+The `:pack-type` child properties of `GtkHeaderBar` and `GtkActionBar` have
 been removed. If you need to programmatically place children, use the
-pack_start() and pack_end() APIs. In ui files, use the type attribute
-on the child element.
+`pack_start()` and `pack_end()` methods. In UI files, use the `type` attribute
+on the `child` element.

-gtk4-builder-tool can help with this conversion, with the --3to4 option
-of the simplify command.
+The `gtk4-builder-tool` utility can help with this conversion, with the
+`--3to4` option of the `simplify` command.

 ### Adapt to GtkStack, GtkAssistant and GtkNotebook API changes

@@ -1,4 +1,5 @@
-# Using GTK on Apple macOS {#gtk-osx}
+Title: Using GTK on Apple macOS
+Slug: gtk-osx

 The Apple macOS port of GTK is an implementation of GDK (and therefore GTK)
 on top of the Quartz API.
@@ -0,0 +1,65 @@
+Title: Overview
+
+GTK is a library for creating graphical user interfaces. It works on many
+UNIX-like platforms, Windows, and macOS. GTK is released under the terms of
+the [GNU Library General Public License][gnu-lgpl], which allows for flexible
+licensing of client applications. GTK has a C-based, object-oriented
+architecture that allows for maximum flexibility and portability; there are
+bindings for many other languages, including C++, Objective-C, Guile/Scheme, Perl,
+Python, JavaScript, Rust, Go, TOM, Ada95, Free Pascal, and Eiffel.
+
+The GTK toolkit contains "widgets": GUI components such as buttons, text
+input, or windows.
+
+GTK depends on the following libraries:
+
+ - **GLib**: a general-purpose utility library, not specific to graphical
+   user interfaces. GLib provides many useful data types, macros, type
+   conversions, string utilities, file utilities, a main loop abstraction,
+   and so on. More information available on the [GLib website][glib].
+ - **GObject**: A library that provides a type system, a collection of
+   fundamental types including an object type, and a signal system. More
+   information available on the [GObject website][gobject].
+ - **GIO**: A modern, easy-to-use VFS API including abstractions for files,
+   drives, volumes, stream IO, as well as network programming and IPC though
+   DBus. More information available on the [GIO website][gio].
+ - **Cairo**: Cairo is a 2D graphics library with support for multiple
+   output devices. More information available on the [Cairo website][cairo].
+ - **OpenGL**: OpenGL is the premier environment for developing portable,
+   interactive 2D and 3D graphics applications. More information available
+   on the [Khronos website][opengl].
+ - **Pango**: Pango is a library for internationalized text handling. It
+   centers around the `PangoLayout` object, representing a paragraph of
+   text.  Pango provides the engine for `GtkTextView`, `GtkLabel`,
+   `GtkEntry`, and all GTK widgets that display text. More information
+   available on the [Pango website][pango].
+ - **gdk-pixbuf**: A small, portable library which allows you to create
+   `GdkPixbuf` ("pixel buffer") objects from image data or image files. You
+   can use `GdkPixbuf` in combination with widgets like `GtkImage` to
+   display images. More information available on the
+   [gdk-pixbuf website][gdkpixbuf].
+ - **graphene**: A small library which provides vector and matrix
+   datatypes and operations. Graphene provides optimized implementations
+   using various SIMD instruction sets such as SSE and ARM NEON. More
+   information available on the [Graphene website][graphene]
+
+GTK is divided into three parts:
+
+ - **GDK**: GDK is the abstraction layer that allows GTK to support multiple
+   windowing systems. GDK provides window system facilities on Wayland, X11,
+   Microsoft Windows, and Apple macOS.
+ - **GSK**: GSK is an API for creating a scene graph from drawing operation,
+   called "nodes", and rendering it using different backends. GSK provides
+   renderers for OpenGL, Vulkan and Cairo.
+ - **GTK**: The GUI toolkit, containing UI elements, layout managers, data
+   storage types for efficient use in GUI applications, and much more.
+
+[gnu-lgpl]: https://www.gnu.org/licenses/old-licenses/lgpl-2.1.en.html
+[glib]: https://developer.gnome.org/glib/stable/
+[gobject]: https://developer.gnome.org/gobject/stable/
+[gio]: https://developer.gnome.org/gio/stable/
+[cairo]: https://www.cairographics.org/manual/
+[opengl]: https://www.opengl.org/about/
+[pango]: https://pango.gnome.org/
+[gdkpixbuf]: https://developer.gnome.org/gdk-pixbuf/stable/
+[graphene]: https://ebassi.github.io/graphene/
@@ -1,4 +1,5 @@
-# Common Questions {#gtk-question-index}
+Title: Common Questions
+Slug: gtk-question-index

 This is an "index" of the reference manual organized by common "How do
 I..." questions. If you aren't sure which documentation to read for
@@ -1,4 +1,5 @@
-# Contact information and bug reports {#gtk-resources}
+Title: Contact information and bug reports
+Slug: gtk-resources

 ## Opening a bug or feature request

@@ -1,4 +1,5 @@
-# Running and debugging GTK Applications {#gtk-running}
+Title: Running and debugging GTK Applications
+Slug: gtk-running

 ## Environment variables

@@ -9,55 +10,70 @@ to determine paths to look for certain files. The [X11](#x11-envar),
 [Broadway](#broadway-envar) GDK backends use some additional
 environment variables.

-### GTK_DEBUG {#GTK_Debug-Options}
+### `GTK_DEBUG`

 This variable can be set to a list of debug options, which cause GTK to
 print out different types of debugging information. Some of these options
 are only available when GTK has been configured with `-Ddebug=true`.

-actions
- : Actions and menu models
-builder
- : GtkBuilder support
-geometry
- : Size allocation
-icontheme
- : Icon themes
-keybindings
- : Keybindings
-modules
- : Loading of modules
-printing
- : Printing support
-size-request
- : Size requests
-text
- : Text widget internals
-tree
- : Tree widget internals
- 
-  A number of keys are influencing behavior instead of just logging:
-  
-interactive
- : Open the [interactive debugger](#interactive-debugging)
-no-css-cache
- : Bypass caching for CSS style properties
-touchscreen
- : Pretend the pointer is a touchscreen device
-updates
- : Visual feedback about window updates
-resize
- : Highlight resizing widgets
-layout
- : Show layout borders
-snapshot
- : Include debug render nodes in the generated snapshots
- 
+`actions`
+: Actions and menu models
+
+`builder`
+: GtkBuilder support
+
+`geometry`
+: Size allocation
+
+`icontheme`
+: Icon themes
+
+`keybindings`
+: Keybindings
+
+`modules`
+: Loading of modules
+
+`printing`
+: Printing support
+
+`size-request`
+: Size requests
+
+`text`
+: Text widget internals
+
+`tree`
+: Tree widget internals
+
+A number of keys are influencing behavior instead of just logging:
+
+`interactive`
+: Open the [interactive debugger](#interactive-debugging)
+
+`no-css-cache`
+: Bypass caching for CSS style properties
+
+`touchscreen`
+: Pretend the pointer is a touchscreen device
+
+`updates`
+: Visual feedback about window updates
+
+`resize`
+: Highlight resizing widgets
+
+`layout`
+: Show layout borders
+
+`snapshot`
+: Include debug render nodes in the generated snapshots
+
 The special value `all` can be used to turn on all debug options.
 The special value `help` can be used to obtain a list of all
 supported debug options.

-### GTK_PATH {#gtk-path}
+### `GTK_PATH`

 Specifies a list of directories to search when GTK is looking for
 dynamically loaded objects such as input method modules and print
@@ -89,7 +105,7 @@ too, which makes it unsuitable for setting it system-wide (or
 session-wide), since doing so will cause applications using
 different GTK versions to see incompatible modules.

-### GTK_IM_MODULE
+### `GTK_IM_MODULE`

 Specifies an IM module to use in preference to the one determined
 from the locale. If this isn't set and you are running on the system
@@ -98,25 +114,25 @@ be used for the default IM module. This also can be a colon-separated
 list of input-methods, which GTK will try in turn until it finds one
 available on the system.

-### GTK_MEDIA
+### `GTK_MEDIA`

-Specifies what backend to load for #GtkMediaFile. The possible values
+Specifies what backend to load for [class@Gtk.MediaFile]. The possible values
 depend on what options GTK was built with, and can include 'gstreamer',
 'ffmpeg' and 'none'. If set to 'none', media playback will be unavailable.
 The special value 'help' can be used to obtain a list of all supported
 media backends.

-### GTK_EXE_PREFIX
+### `GTK_EXE_PREFIX`

 If set, GTK uses `$GTK_EXE_PREFIX/lib` instead of the libdir
 configured when GTK was compiled.

-### GTK_DATA_PREFIX
+### `GTK_DATA_PREFIX`

 If set, GTK uses `$GTK_DATA_PREFIX` instead of the prefix
 configured when GTK was compiled.

-### GTK_THEME
+### `GTK_THEME`

 If set, makes GTK use the named theme instead of the theme
 that is specified by the gtk-theme-name setting. This is intended
@@ -129,7 +145,7 @@ The following environment variables are used by GdkPixbuf, GDK or
 Pango, not by GTK itself, but we list them here for completeness
 nevertheless.

-### GDK_PIXBUF_MODULE_FILE
+### `GDK_PIXBUF_MODULE_FILE`

 Specifies the file listing the GdkPixbuf loader modules to load.
 This environment variable overrides the default value
@@ -139,151 +155,185 @@ specified when GTK was configured, usually `/usr/lib`.)
 The `loaders.cache` file is generated by the
 `gdk-pixbuf-query-loaders` utility.

-### GDK_DEBUG
+### `GDK_DEBUG`

 This variable can be set to a list of debug options, which cause GDK to
 print out different types of debugging information. Some of these options
 are only available when GTK has been configured with `-Ddebug=true`.

-cursor
- : Information about cursor objects (only win32)
-eventloop
- : Information about event loop operation (mostly Quartz)
-misc
- : Miscellaneous information
-frames
- : Information about the frame clock
-settings
- : Information about xsettings
-selection
- : Information about selections
-clipboard
- : Information about clipboards
-dnd
- : Information about drag-and-drop
-opengl
- : Information about OpenGL
-vulkan
- : Information about Vulkan
- 
+`cursor`
+: Information about cursor objects (only win32)
+
+`eventloop`
+: Information about event loop operation (mostly macOS)
+
+`misc`
+: Miscellaneous information
+
+`frames`
+: Information about the frame clock
+
+`settings`
+: Information about xsettings
+
+`selection`
+: Information about selections
+
+`clipboard`
+: Information about clipboards
+
+`dnd`
+: Information about drag-and-drop
+
+`opengl`
+: Information about OpenGL
+
+`vulkan`
+: Information about Vulkan
+
 A number of options affect behavior instead of logging:

-nograbs
- : Turn off all pointer and keyboard grabs
-gl-disable
- : Disable OpenGL support
-gl-software
- : Force OpenGL software rendering
-gl-texture-rect
- : Use the OpenGL texture rectangle extension, if available
-gl-legacy
- : Use a legacy OpenGL context
-gl-gles
- : Use a GLES OpenGL context
-vulkan-disable
- : Disable Vulkan support
-vulkan-validate
- : Load the Vulkan validation layer, if available
- 
-The special value `all` can be used to turn on all
-debug options. The special value `help` can be used
-to obtain a list of all supported debug options.
+`nograbs`
+: Turn off all pointer and keyboard grabs

-### GSK_DEBUG {#GSK-Debug-Options}
+`gl-disable`
+: Disable OpenGL support
+
+`gl-software`
+: Force OpenGL software rendering
+
+`gl-texture-rect`
+: Use the OpenGL texture rectangle extension, if available
+
+`gl-legacy`
+: Use a legacy OpenGL context
+
+`gl-gles`
+: Use a GLES OpenGL context
+
+`vulkan-disable`
+: Disable Vulkan support
+
+`vulkan-validate`
+: Load the Vulkan validation layer, if available
+
+The special value `all` can be used to turn on all debug options. The special
+value `help` can be used to obtain a list of all supported debug options.
+
+### `GSK_DEBUG`

 This variable can be set to a list of debug options, which cause GSK to
 print out different types of debugging information. Some of these options
 are only available when GTK has been configured with `-Ddebug=true`.

-renderer
- : General renderer information
-cairo
- : cairo renderer information
-opengl
- : OpenGL renderer information
-shaders
- : Shaders
-surface
- : Surfaces
-vulkan
- : Vulkan renderer information
-fallback
- : Information about fallbacks
-glyphcache
- : Information about glyph caching
+`renderer`
+: General renderer information

-  A number of options affect behavior instead of logging:
+`cairo`
+: cairo renderer information

-diff
- : Show differences
-geometry
- : Show borders
-full-redraw
- : Force full redraws for every frame
-sync
- : Sync after each frame
-vulkan-staging-image
- : Use a staging image for Vulkan texture upload
-vulkan-staging-buffer
- : Use a staging buffer for Vulkan texture upload
+`opengl`
+: OpenGL renderer information

-The special value `all` can be used to turn on all
-debug options. The special value `help` can be used
-to obtain a list of all supported debug options.
+`shaders`
+: Shaders

-### GDK_BACKEND
+`surface`
+: Surfaces
+
+`vulkan`
+: Vulkan renderer information
+
+`fallback`
+: Information about fallbacks
+
+`glyphcache`
+: Information about glyph caching
+
+A number of options affect behavior instead of logging:
+
+`diff`
+: Show differences
+
+`geometry`
+: Show borders
+
+`full-redraw`
+: Force full redraws for every frame
+
+`sync`
+: Sync after each frame
+
+`vulkan-staging-image`
+: Use a staging image for Vulkan texture upload
+
+`vulkan-staging-buffer`
+: Use a staging buffer for Vulkan texture upload
+
+The special value `all` can be used to turn on all debug options. The special
+value `help` can be used to obtain a list of all supported debug options.
+
+### `GDK_BACKEND`

 If set, selects the GDK backend to use. Selecting a backend
 requires that GTK is compiled with support for that backend.
 The following backends can be selected, provided they are
 included in the GDK libraries you are using:

-quartz
- : Selects the native Quartz backend
-win32
- : Selects the native backend for Microsoft Windows
-x11
- : Selects the native backend for connecting to X11 servers
-broadway
- : Selects the Broadway backend for display in web browsers
-wayland
- : Selects the Wayland backend for connecting to Wayland compositors
+`quartz`
+: Selects the native Quartz backend
+
+`win32`
+: Selects the native backend for Microsoft Windows
+
+`x11`
+: Selects the native backend for connecting to X11 servers
+
+`broadway`
+: Selects the Broadway backend for display in web browsers
+
+`wayland`
+: Selects the Wayland backend for connecting to Wayland compositors

 This environment variable can contain a comma-separated list of
 backend names, which are tried in order. The list may also contain
-a *, which means: try all remaining backends. The special value
+a `*`, which means: try all remaining backends. The special value
 `help` can be used to make GDK print out a list of all available
 backends. For more information about selecting backends,
-see the gdk_display_manager_get() function.
+see the [func@Gdk.DisplayManager.get] function.

-### GDK_VULKAN_DEVICE
+### `GDK_VULKAN_DEVICE`

 This variable can be set to the index of a Vulkan device to override
 the default selection of the device that is used for Vulkan rendering.
 The special value `list` can be used to obtain a list of all Vulkan
 devices.

-### GSK_RENDERER
+### `GSK_RENDERER`

 If set, selects the GSK renderer to use. The following renderers can
 be selected, provided they are included in the GTK library you are
 using and the GDK backend supports them:

-help
- : Prints information about available options
-broadway
- : Selects the Broadway-backend specific renderer
-cairo
- : Selects the fallback Cairo renderer
-gl
- : Selects the default OpenGL renderer
-vulkan
- : Selects the Vulkan renderer
+`help`
+: Prints information about available options

-### GTK_CSD
+`broadway`
+: Selects the Broadway-backend specific renderer

-The default value of this environment variable is 1. If changed
-to 0, this disables the default use of client-side decorations
+`cairo`
+: Selects the fallback Cairo renderer
+
+`gl`
+: Selects the default OpenGL renderer
+
+`vulkan`
+: Selects the Vulkan renderer
+
+### `GTK_CSD`
+
+The default value of this environment variable is `1`. If changed
+to `0`, this disables the default use of client-side decorations
 on GTK windows, thus making the window manager responsible for
 drawing the decorations of windows that do not have a custom
 titlebar widget.
@@ -292,25 +342,28 @@ CSD is always used for windows with a custom titlebar widget set,
 as the WM should not draw another titlebar or other decorations
 around the custom one.

-### GTK_A11Y
+### `GTK_A11Y`

 If set, selects the accessibility backend to use. The following
 backends can be selected, provided they are included in the GTK
 library you are using:

-help
- : Prints information about available options
-atspi
- : Selects the AT-SPI accessibility backend
-test
- : Selects the test backend
-none
- : Disables the accessibility backend
+`help`
+: Prints information about available options
+
+`atspi`
+: Selects the AT-SPI accessibility backend
+
+`test`
+: Selects the test backend
+
+`none`
+: Disables the accessibility backend

 The `test` accessibility backend is recommended for test suites and remote
 continuous integration pipelines.

-### XDG_DTA_HOME, XDG_DATA_DIRS
+### `XDG_DTA_HOME`, `XDG_DATA_DIRS`

 GTK uses these environment variables to locate icon themes
 and MIME information. For more information, see the
@@ -318,16 +371,16 @@ and MIME information. For more information, see the
 the [Shared MIME-Info Database](https://freedesktop.org/Standards/shared-mime-info-spec)
 and the [Base Directory Specification](https://freedesktop.org/Standards/basedir-spec).

-### DESKTOP_STARTUP_ID
+### `DESKTOP_STARTUP_ID`

 GTK uses this environment variable to provide startup notification
 according to the [Startup Notification Spec](https://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt).
 Following the specification, GTK unsets this variable after reading
 it (to keep it from leaking to child processes). So, if you need its
 value for your own purposes, you have to read it before calling
-gtk_init().
+[func@Gtk.init].

-## Interactive debugging {#interactive-debugging}
+## Interactive debugging

 ![The inspector](inspector.png)

@@ -343,9 +396,9 @@ limits what it can do. It is meant as a complement to full-blown
 debuggers and system tracing facilities such as DTrace, not as a
 replacement.

-To enable the GTK inspector, you can use the Control-Shift-I or
-Control-Shift-D keyboard shortcuts, or set the `GTK_DEBUG=interactive`
-environment variable.
+To enable the GTK inspector, you can use the <kbd>Control</kbd>+<kbd>Shift</kbd>+<kbd>I</kbd> or
+<kbd>Control</kbd>+<kbd>Shift</kbd>+<kbd>D</kbd> keyboard shortcuts, or
+set the `GTK_DEBUG=interactive` environment variable.

 There are a few more environment variables that can be set to influence
 how the inspector renders its UI. `GTK_INSPECTOR_DISPLAY` and
@@ -357,7 +410,7 @@ the GTK inspector. The keyboard shortcuts can be disabled with the
 `enable-inspector-keybinding` key in the `org.gtk.Settings.Debug`
 GSettings schema.

-## Profiling {#profiling}
+## Profiling

 GTK supports profiling with sysprof. It exports timing information
 about frameclock phases and various characteristics of GskRenderers
@@ -1,23 +1,24 @@
-# GTK Accessibility {#gtk-accessibility}
+Title: GTK Accessibility
+Slug: gtk-accessibility

 ## The standard accessibility interface

-The #GtkAccessible interface provides the accessibility information about
+The `GtkAccessible` interface provides the accessibility information about
 an application's user interface elements. Assistive technology (AT)
 applications, like Orca, convey this information to users with disabilities,
 or reduced abilities, to help them use the application.

 Standard GTK controls implement the #GtkAccessible interface and are thus
 accessible to ATs by default. This means that if you use GTK controls such
-as #GtkButton, #GtkEntry, or #GtkListView, you only need to supply
+as `GtkButton`, `GtkEntry`, or `GtkListView`, you only need to supply
 application-specific details when the defaults values are incomplete. You
-can do this by setting the appropriate properties in your #GtkBuilder
+can do this by setting the appropriate properties in your `GtkBuilder`
 template and UI definition files, or by setting the properties defined by
-the #GtkAccessible interface.
+the `GtkAccessible` interface.

-If you are implementing your own #GtkWidget derived type, you will need to
-set the #GtkAccessible properties yourself, and provide an implementation
-of the #GtkAccessible virtual functions.
+If you are implementing your own `GtkWidget` derived type, you will need to
+set the `GtkAccessible` properties yourself, and provide an implementation
+of the `GtkAccessible` virtual functions.

 ## Accessible roles and attributes

@@ -45,39 +46,39 @@ Each role name is part of the #GtkAccessibleRole enumeration.

 | Role name | Description | Related GTK widget |
 |-----------|-------------|--------------------|
-| `BUTTON` | A control that performs an action when pressed | #GtkButton, #GtkLinkButton, #GtkExpander |
-| `CHECKBOX` | A control that has three possible value: `true`, `false`, or `undefined` | #GtkCheckButton |
-| `COMBOBOX` | A control that can be expanded to show a list of possible values to select | #GtkComboBox |
-| `COLUMN_HEADER` | A header in a columned list | #GtkColumnView |
-| `DIALOG` | A dialog that prompts the user to enter information or require a response | #GtkDialog and subclasses |
-| `GRID` | A grid of items | #GtkFlowBox, #GtkGridView |
-| `GRID_CELL` | An item in a grid | #GtkFlowBoxChild, #GtkGridView, #GtkColumnView |
-| `IMG` | An image | #GtkImage, #GtkPicture |
-| `LABEL` | A visible name or caption for a user interface component | #GtkLabel |
-| `LINK` | A clickable hyperlink | #GtkLinkButton |
-| `LIST` | A list of items | #GtkListBox |
-| `LIST_ITEM` | An item in a list | #GtkListBoxRow |
-| `MENU` | A menu | #GtkPopoverMenu |
-| `MENU_BAR` | A menubar | #GtkPopoverMenuBar |
-| `MENU_ITEM` | A menu item | Items in #GtkPopoverMenu |
-| `MENU_ITEM_CHECKBOX` | Check menu item | Items in #GtkPopoverMenu |
-| `MENU_ITEM_RADIO` | Radio menu item | Items in #GtkPopoverMenu |
-| `METER` | Represents a value within a known range | #GtkLevelBar |
-| `NONE` | Not represented in the accessibility tree | the slider of a #GtkScale |
-| `PROGRESS_BAR` | An element that display progress | #GtkProgressBar |
-| `RADIO` | A checkable input in a group of radio roles | #GtkCheckButton |
-| `ROW` | A row in a columned list | #GtkColumnView |
-| `SCROLLBAR` | A graphical object controlling the scrolling of content | #GtkScrollbar |
-| `SEARCH_BOX` | A text box for entering search criteria | #GtkSearchEntry |
-| `SEPARATOR` | A divider that separates sections of content or groups of items | #GtkSeparator |
-| `SPIN_BUTTON` | A range control that allows seelcting among discrete choices | #GtkSpinButton |
-| `SWITCH` | A control that represents on/off values | #GtkSwitch |
-| `TAB` | A tab in a list of tabs for switching pages | #GtkStackSwitcher, #GtkNotebook |
-| `TAB_LIST` | A list of tabs for switching pages | #GtkStackSwitcher, #GtkNotebook |
-| `TAB_PANEL` | A page in a notebook or stack | #GtkStack |
-| `TEXT_BOX` | A type of input that allows free-form text as its value. | #GtkEntry, #GtkPasswordEntry, #GtkTextView |
-| `TREE_GRID` | A treeview-like columned list | #GtkColumnView |
-| `WINDOW` | An application window | #GtkWindow |
+| `BUTTON` | A control that performs an action when pressed | [class@Gtk.Button], [class@Gtk.LinkButton], [class@Gtk.Expander] |
+| `CHECKBOX` | A control that has three possible value: `true`, `false`, or `undefined` | [class@Gtk.CheckButton] |
+| `COMBOBOX` | A control that can be expanded to show a list of possible values to select | [class@Gtk.ComboBox] |
+| `COLUMN_HEADER` | A header in a columned list | [class@Gtk.ColumnView] |
+| `DIALOG` | A dialog that prompts the user to enter information or require a response | [class@Gtk.Dialog] and subclasses |
+| `GRID` | A grid of items | [class@Gtk.FlowBox], [class@Gtk.GridView] |
+| `GRID_CELL` | An item in a grid | [class@Gtk.FlowBoxChild], [class@Gtk.GridView], [class@Gtk.ColumnView] |
+| `IMG` | An image | [class@Gtk.Image], [class@Gtk.Picture] |
+| `LABEL` | A visible name or caption for a user interface component | [class@Gtk.Label] |
+| `LINK` | A clickable hyperlink | [class@Gtk.LinkButton] |
+| `LIST` | A list of items | [class@Gtk.ListBox] |
+| `LIST_ITEM` | An item in a list | [class@Gtk.ListBoxRow] |
+| `MENU` | A menu | [class@Gtk.PopoverMenu] |
+| `MENU_BAR` | A menubar | [class@Gtk.PopoverMenuBar] |
+| `MENU_ITEM` | A menu item | Items in [class@Gtk.PopoverMenu] |
+| `MENU_ITEM_CHECKBOX` | Check menu item | Items in [class@Gtk.PopoverMenu] |
+| `MENU_ITEM_RADIO` | Radio menu item | Items in [class@Gtk.PopoverMenu] |
+| `METER` | Represents a value within a known range | [class@Gtk.LevelBar] |
+| `NONE` | Not represented in the accessibility tree | the slider of a [class@Gtk.Scale] |
+| `PROGRESS_BAR` | An element that display progress | [class@Gtk.ProgressBar] |
+| `RADIO` | A checkable input in a group of radio roles | [class@Gtk.CheckButton] |
+| `ROW` | A row in a columned list | [class@Gtk.ColumnView] |
+| `SCROLLBAR` | A graphical object controlling the scrolling of content | [class@Gtk.Scrollbar] |
+| `SEARCH_BOX` | A text box for entering search criteria | [class@Gtk.SearchEntry] |
+| `SEPARATOR` | A divider that separates sections of content or groups of items | [class@Gtk.Separator] |
+| `SPIN_BUTTON` | A range control that allows seelcting among discrete choices | [class@Gtk.SpinButton] |
+| `SWITCH` | A control that represents on/off values | [class@Gtk.Switch] |
+| `TAB` | A tab in a list of tabs for switching pages | [class@Gtk.StackSwitcher], [class@Gtk.Notebook] |
+| `TAB_LIST` | A list of tabs for switching pages | [class@Gtk.StackSwitcher], [class@Gtk.Notebook] |
+| `TAB_PANEL` | A page in a notebook or stack | [class@Gtk.Stack] |
+| `TEXT_BOX` | A type of input that allows free-form text as its value. | [class@Gtk.Entry], [class@Gtk.PasswordEntry], [class@Gtk.TextView] |
+| `TREE_GRID` | A treeview-like columned list | [class@Gtk.ColumnView] |
+| `WINDOW` | An application window | [class@Gtk.Window] |
 | `...` | … |

 See the [WAI-ARIA](https://www.w3.org/WAI/PF/aria/appendices#quickref) list
@@ -89,11 +90,11 @@ Attributes provide specific information about an accessible UI
 control, and describe it for the assistive technology applications. GTK
 divides the accessible attributes into three categories:

- - *properties*, described by the values of the #GtkAccessibleProperty
+ - *properties*, described by the values of the `GtkAccessibleProperty`
   enumeration
- - *relations*, described by the values of the #GtkAccessibleRelation
+ - *relations*, described by the values of the `GtkAccessibleRelation`
   enumeration
- - *states*, described by the values of the #GtkAccessibleState enumeration
+ - *states*, described by the values of the `GtkAccessibleState` enumeration

 Each attribute accepts a value of a specific type.

@@ -120,12 +121,12 @@ Each state name is part of the #GtkAccessibleState enumeration.
 | State name | ARIA attribute | Value type | Notes |
 |------------|----------------|------------|-------|
 | %GTK_ACCESSIBLE_STATE_BUSY | “aria-busy” | boolean |
-| %GTK_ACCESSIBLE_STATE_CHECKED | “aria-checked” | #GtkAccessibleTristate | Indicates the current state of a #GtkCheckButton |
-| %GTK_ACCESSIBLE_STATE_DISABLED | “aria-disabled” | boolean | Corresponds to the #GtkWidget:sensitive property on #GtkWidget |
-| %GTK_ACCESSIBLE_STATE_EXPANDED | “aria-expanded” | boolean or undefined | Corresponds to the  #GtkExpander:expanded property on #GtkExpander |
-| %GTK_ACCESSIBLE_STATE_HIDDEN | “aria-hidden” | boolean | Corresponds to the #GtkWidget:visible property on #GtkWidget |
+| %GTK_ACCESSIBLE_STATE_CHECKED | “aria-checked” | #GtkAccessibleTristate | Indicates the current state of a [class@Gtk.CheckButton] |
+| %GTK_ACCESSIBLE_STATE_DISABLED | “aria-disabled” | boolean | Corresponds to the [property@Gtk.Widget:sensitive] property on [class@Gtk.Widget] |
+| %GTK_ACCESSIBLE_STATE_EXPANDED | “aria-expanded” | boolean or undefined | Corresponds to the  [property@Gtk.Expander:expanded] property on [class@Gtk.Expander] |
+| %GTK_ACCESSIBLE_STATE_HIDDEN | “aria-hidden” | boolean | Corresponds to the [property@Gtk.Widget:visible] property on [class@Gtk.Widget] |
 | %GTK_ACCESSIBLE_STATE_INVALID | “aria-invalid” | #GtkAccessibleInvalidState | Set when a widget is showing an error |
-| %GTK_ACCESSIBLE_STATE_PRESSED | “aria-pressed” | #GtkAccessibleTristate | Indicates the current state of a #GtkToggleButton |
+| %GTK_ACCESSIBLE_STATE_PRESSED | “aria-pressed” | #GtkAccessibleTristate | Indicates the current state of a [class@Gtk.ToggleButton] |
 | %GTK_ACCESSIBLE_STATE_SELECTED | “aria-selected” | boolean or undefined | Set when a widget is selected |

 #### List of accessible properties
@@ -180,7 +181,7 @@ Each relation name is part of the #GtkAccessibleRelation enumeration.
 | %GTK_ACCESSIBLE_RELATION_SET_SIZE | “aria-setsize” | integer |

 *Note*: When using gtk_accessible_update_relation() with a relation that
-requires a list of #GtkAccessible instances, you should pass every
+requires a list of `GtkAccessible` instances, you should pass every
 accessible object separately, followed by %NULL. 

 ## Application development rules
@@ -232,12 +233,12 @@ which acts as a proxy to the specific platform's accessibility API:
 Additionally, an ad hoc accessibility backend is available for the GTK
 testsuite, to ensure reproducibility of issues in the CI pipeline.

-## Authoring practices {#authoring-practices}
+## Authoring practices

 The authoring practices are aimed at application developers, as well as
 developers of GUI elements based on GTK.

-Functionally, #GtkAccessible roles, states, properties, and relations are
+Functionally, `GtkAccessible` roles, states, properties, and relations are
 analogous to a CSS for assistive technologies. For screen reader users, for
 instance, the various accessible attributes control the rendering of their
 non-visual experience. Incorrect roles and attributes may result in a
@@ -253,7 +254,7 @@ gtk_widget_class_set_accessible_role (widget_class, GTK_ACCESSIBLE_ROLE_BUTTON);

 is a promise that the widget being created will provide the same keyboard
 interactions expected for a button. An accessible role of a button will not
-turn automatically any widget into a #GtkButton; but if your widget behaves
+turn automatically any widget into a `GtkButton`; but if your widget behaves
 like a button, using the %GTK_ACCESSIBLE_ROLE_BUTTON will allow any
 assistive technology to handle it like they would a #GtkButton.

@@ -319,7 +320,7 @@ as well.
 ### Buttons

 A button is a widget that enables users to trigger an action. While it is
-recommended you use #GtkButton for anything that looks and behaves like a
+recommended you use `GtkButton` for anything that looks and behaves like a
 button, it is possible to apply a button behavior to UI elements like images
 by using a #GtkGestureClick gesture. When doing so, you should:

@@ -329,16 +330,16 @@ by using a #GtkGestureClick gesture. When doing so, you should:
 ### Custom entries

 For custom entries, it is highly recommended that you implement the
-#GtkEditable interface by using a #GtkText widget as delegate. If you
+`GtkEditable` interface by using a `GtkText` widget as delegate. If you
 do this, GTK will make your widgets text editing functionality accessible
-in the same way as a #GtkSpinButton or #GtkSearchEntry.
+in the same way as a `GtkSpinButton` or `GtkSearchEntry`.

 ### Tab-based UI

 If you make a tab-based interface, you should consider using #GtkStack
 as the core, and just make a custom tab widget to control the active
 stack page. When doing so, the following extra steps will ensure that
-your tabs are accessible in the same way as #GtkStackSwitcher or #GtkNotebook:
+your tabs are accessible in the same way as `GtkStackSwitcher` or `GtkNotebook`:

 - Give your tab container the role %GTK_ACCESSIBLE_ROLE_TAB_LIST
 - Give your tab widgets the role %GTK_ACCESSIBLE_ROLE_TAB
@@ -1,4 +1,5 @@
-# List Widget Overview {#ListWidget}
+Title: List Widget Overview
+Slug: gtk-list-widget

 GTK provides powerful widgets to display and edit lists of data. This document
 gives an overview over the concepts and how they work together to allow
@@ -123,7 +124,7 @@ the number of listitems they create such as with gtk_grid_view_set_max_columns()
 and developers running into performance problems should definitely study the
 tradeoffs of those and experiment with them.

-## Choosing the right model {#model-choosing}
+## Choosing the right model

 GTK offers a wide variety of wrapping models which change or supplement an
 existing model (or models) in some way. But when it comes to storing your
@@ -149,7 +150,7 @@ For asymptotic performance comparisons between tree- and array-based
 implementations, see this
 [article](https://en.wikipedia.org/wiki/Dynamic_array#Performance).

-## Displaying trees {#displaying-trees}
+## Displaying trees

 While #GtkTreeView provided built-in support for trees, the list widgets, and
 in particular #GListModel do not. This was a design choice because the common
@@ -165,7 +166,7 @@ rows and provide a similar experience to #GtkTreeView.
 Developers should refer to those objects' API reference for more discussion
 on the topic.

-## List styles {#list-styles}
+## List styles

 One of the advantages of the new list widgets over #GtkTreeViews and cell
 renderers is that they are fully themable using GTK CSS. This provides a
@@ -1,4 +1,5 @@
-# Text Widget Overview {#TextWidget}
+Title: Text Widget Overview
+Slug: gtk-textview

 GTK has an extremely powerful framework for multiline text editing.  The
 primary objects involved in the process are #GtkTextBuffer, which represents the 
@@ -1,4 +1,5 @@
-# Tree and List Widget Overview {#TreeWidget}
+Title: Tree and List Widget Overview
+Slug: gtk-treeview

 To create a tree or list in GTK, use the #GtkTreeModel interface in
 conjunction with the #GtkTreeView widget.  This widget is designed around
@@ -0,0 +1,13 @@
+// SPDX-FileCopyrightText: 2021 GNOME Foundation
+// SPDX-License-Identifier: LGPL-2.1-or-later
+
+// A map between namespaces and base URLs for their online documentation
+baseURLs = [
+    [ 'Gdk', 'https://gnome.pages.gitlab.gnome.org/gtk/gdk4/' ],
+    [ 'GdkWayland', 'https://gnome.pages.gitlab.gnome.org/gtk/gdk4-wayland/' ],
+    [ 'GdkX11', 'https://gnome.pages.gitlab.gnome.org/gtk/gdk4-x11/' ],
+    [ 'Gsk', 'https://gnome.pages.gitlab.gnome.org/gtk/gsk4/' ],
+    [ 'Gtk', 'https://gnome.pages.gitlab.gnome.org/gtk/gtk4/' ],
+    [ 'Pango', 'https://gnome.pages/gitlab.gnome.org/pango/pango/' ],
+    [ 'PangoCairo', 'https://gnome.pages.gitlab.gnome.org/pango/pangocairo/' ],
+]
@@ -1 +0,0 @@
-@GTK_VERSION@
@@ -0,0 +1,89 @@
+Title: Widget Gallery
+
+## Display widgets
+
+[![label](label.png)](class.Label.html)
+[![spinner](spinner.png)](class.Spinner.html)
+[![statusbar](statusbar.png)](class.Statusbar.html)
+[![levelbar](levelbar.png)](class.LevelBar.html)
+[![progressbar](progressbar.png)](class.ProgressBar.html)
+[![infobar](info-bar.png)](class.InfoBar.html)
+[![scrollbar](scrollbar.png)](class.Scrollbar.html)
+[![image](image.png)](class.Image.html)
+[![picture](picture.png)](class.Picture.html)
+[![separator](separator.png)](class.Separator.html)
+[![textview](multiline-text.png)](class.TextView.html)
+[![scale](scales.png)](class.Scale.html)
+[![glarea](glarea.png)](class.GLArea.html)
+[![drawingarea](drawingarea.png)](class.DrawingArea.html)
+[![video](video.png)](class.Video.html)
+[![mediacontrols](media-controls.png)](class.MediaControls.html)
+[![windowcontrols](windowcontrols.png)](class.WindowControls.html)
+[![menubar](menubar.png)](class.PopoverMenuBar.html)
+[![calendar](calendar.png)](class.Calendar.html)
+[![emojichooser](emojichooser.png)](class.EmojiChooser.html)
+[![menu](menu.png)](class.PopoverMenu.html)
+
+## Buttons
+
+[![button](button.png)](class.Button.html)
+[![togglebutton](toggle-button.png)](class.ToggleButton.html)
+[![linkbutton](link-button.png)](class.LinkButton.html)
+[![checkbutton](check-button.png)](class.CheckButton.html)
+[![checkbutton](radio-button.png)](class.CheckButton.html)
+[![menubutton](menu-button.png)](class.MenuButton.html)
+[![lockbutton](lockbutton.png)](class.LockButton.html)
+[![volumebutton](volumebutton.png)](class.VolumeButton.html)
+[![switch](switch.png)](class.Switch.html)
+[![combobox](combo-box.png)](class.ComboBox.html)
+[![comboboxtext](combo-box-text.png)](class.ComboBoxText.html)
+[![dropdown](drop-down.png)](class.DropDown.html)
+[![colorbutton](color-button.png)](class.ColorButton.html)
+[![fontbutton](font-button.png)](class.FontButton.html)
+[![appchooserbutton](appchooserbutton.png)](class.AppChooserButton.html)
+
+## Entries
+
+[![entry](entry.png)](class.Entry.html)
+[![searchentry](search-entry.png)](class.SearchEntry.html)
+[![passwordentry](password-entry.png)](class.PasswordEntry.html)
+[![spinbutton](spinbutton.png)](class.SpinButton.html)
+[![editablelabel](editable-label.png)](class.EditableLabel.html)
+
+## Containers
+
+[![box](box.png)](class.Box.html)
+[![grid](grid.png)](class.Grid.html)
+[![centerbox](centerbox.png)](class.CenterBox.html)
+[![scrolledwindow](scrolledwindow.png)](class.ScrolledWindow.html)
+[![panes](panes.png)](class.Paned.html)
+[![frame](frame.png)](class.Frame.html)
+[![expander](expander.png)](class.Expander.html)
+[![searchbar](search-bar.png)](class.SearchBar.html)
+[![actionbar](action-bar.png)](class.ActionBar.html)
+[![headerbar](headerbar.png)](class.HeaderBar.html)
+[![notebook](notebook.png)](class.Notebook.html)
+[![listbox](list-box.png)](class.ListBox.html)
+[![flowbox](flow-box.png)](class.FlowBox.html)
+[![treeview](list-and-tree.png)](class.TreeView.html)
+[![iconview](icon-view.png)](class.IconView.html)
+[![overlay](overlay.png)](class.Overlay.html)
+[![stack](stack.png)](class.Stack.html)
+[![stackswitcher](stackswitcher.png)](class.StackSwitcher.html)
+[![stacksidebar](sidebar.png)](class.StackSidebar.html)
+[![popover](popover.png)](class.Popover.html)
+
+## Windows
+
+[![window](window.png)](class.Window.html)
+[![dialog](dialog.png)](class.Dialog.html)
+[![messagedialog](messagedialog.png)](class.MessageDialog.html)
+[![aboutdialog](aboutdialog.png)](class.AboutDialog.html)
+[![assistant](assistant.png)](class.Assistant.html)
+[![colorchooser](colorchooser.png)](class.ColorChooserDialog.html)
+[![filechooser](filechooser.png)](class.FileChooserDialog.html)
+[![fontchooser](fontchooser.png)](class.FontChooserDialog.html)
+[![appchooserdialog](appchooserdialog.png)](class.AppChooserDialog.html)
+[![pagesetupdialog](pagesetupdialog.png)](class.PageSetupUnixDialog.html)
+[![printdialog](printdialog.png)](class.PrintUnixDialog.html)
+[![shortcutswindow](shortcuts-window.png)](class.ShortcutsWindow.html)
@@ -1,109 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE para PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-]>
-<para>
-<section id="visual-display">
-  <title>Display</title>
-  <para role="gallery">
-    <link linkend="GtkLabel"><inlinegraphic fileref="label.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkSpinner"><inlinegraphic fileref="spinner.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkStatusbar"><inlinegraphic fileref="statusbar.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkLevelBar"><inlinegraphic fileref="levelbar.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkProgressBar"><inlinegraphic fileref="progressbar.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkInfoBar"><inlinegraphic fileref="info-bar.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkScrollbar"><inlinegraphic fileref="scrollbar.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkImage"><inlinegraphic fileref="image.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkPicture"><inlinegraphic fileref="picture.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkSeparator"><inlinegraphic fileref="separator.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkTextView"><inlinegraphic fileref="multiline-text.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkScale"><inlinegraphic fileref="scales.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkCalendar"><inlinegraphic fileref="calendar.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkGLArea"><inlinegraphic fileref="glarea.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkDrawingArea"><inlinegraphic fileref="drawingarea.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkVideo"><inlinegraphic fileref="video.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkMediaControls"><inlinegraphic fileref="media-controls.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkWindowControls"><inlinegraphic fileref="windowcontrols.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkEmojiChooser"><inlinegraphic fileref="emojichooser.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkPopoverMenu"><inlinegraphic fileref="menu.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkPopoverMenuBar"><inlinegraphic fileref="menubar.png" format="PNG"></inlinegraphic></link>
-  </para>
-</section>
-
-<section id="visual-buttons">
-  <title>Buttons</title>
-  <para role="gallery">
-    <link linkend="GtkButton"><inlinegraphic fileref="button.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkToggleButton"><inlinegraphic fileref="toggle-button.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkLinkButton"><inlinegraphic fileref="link-button.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkCheckButton"><inlinegraphic fileref="check-button.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkMenuButton"><inlinegraphic fileref="menu-button.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkLockButton"><inlinegraphic fileref="lockbutton.png" format="PNG"></inlinegraphic></link>
-   <link linkend="GtkVolumeButton"><inlinegraphic fileref="volumebutton.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkSwitch"><inlinegraphic fileref="switch.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkComboBox"><inlinegraphic fileref="combo-box.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkComboBoxText"><inlinegraphic fileref="combo-box-text.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkDropDown"><inlinegraphic fileref="drop-down.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkColorButton"><inlinegraphic fileref="color-button.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkFontButton"><inlinegraphic fileref="font-button.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkAppChooserButton"><inlinegraphic fileref="appchooserbutton.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkFileChooserButton"><inlinegraphic fileref="file-button.png" format="PNG"></inlinegraphic></link>
-  </para>
-</section>
-
-<section id="visual-entries">
-  <title>Entries</title>
-  <para role="gallery">
-    <link linkend="GtkEntry"><inlinegraphic fileref="entry.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkSearchEntry"><inlinegraphic fileref="search-entry.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkPasswordEntry"><inlinegraphic fileref="password-entry.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkSpinButton"><inlinegraphic fileref="spinbutton.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkEditableLabel"><inlinegraphic fileref="editable-label.png" format="PNG"></inlinegraphic></link>
-  </para>
-</section>
-
-<section id="visual-containers">
-  <title>Containers</title>
-  <para role="gallery">
-    <link linkend="GtkBox"><inlinegraphic fileref="box.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkGrid"><inlinegraphic fileref="grid.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkCenterBox"><inlinegraphic fileref="centerbox.png" format="PNG"></inlinegraphic></link>
-  </para>
-  <para role="gallery">
-    <link linkend="GtkScrolledWindow"><inlinegraphic fileref="scrolledwindow.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkPaned"><inlinegraphic fileref="panes.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkFrame"><inlinegraphic fileref="frame.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkExpander"><inlinegraphic fileref="expander.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkSearchBar"><inlinegraphic fileref="search-bar.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkActionBar"><inlinegraphic fileref="action-bar.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkHeaderBar"><inlinegraphic fileref="headerbar.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkNotebook"><inlinegraphic fileref="notebook.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkListBox"><inlinegraphic fileref="list-box.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkFlowBox"><inlinegraphic fileref="flow-box.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkTreeView"><inlinegraphic fileref="list-and-tree.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkIconView"><inlinegraphic fileref="icon-view.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkOverlay"><inlinegraphic fileref="overlay.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkStack"><inlinegraphic fileref="stack.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkStackSwitcher"><inlinegraphic fileref="stackswitcher.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkStackSidebar"><inlinegraphic fileref="sidebar.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkPopover"><inlinegraphic fileref="popover.png" format="PNG"></inlinegraphic></link>
-  </para>
-</section>
-
-<section id="visual-windows">
-  <title>Windows</title>
-  <para role="gallery">
-    <link linkend="GtkWindow"><inlinegraphic fileref="window.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkMessageDialog"><inlinegraphic fileref="messagedialog.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkAboutDialog"><inlinegraphic fileref="aboutdialog.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkAssistant"><inlinegraphic fileref="assistant.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkColorChooserDialog"><inlinegraphic fileref="colorchooser.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkFileChooserDialog"><inlinegraphic fileref="filechooser.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkFontChooserDialog"><inlinegraphic fileref="fontchooser.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkAppChooserDialog"><inlinegraphic fileref="appchooserdialog.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkPageSetupUnixDialog"><inlinegraphic fileref="pagesetupdialog.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkPrintUnixDialog"><inlinegraphic fileref="printdialog.png" format="PNG"></inlinegraphic></link>
-    <link linkend="GtkShortcutsWindow"><inlinegraphic fileref="shortcuts-window.png" format="PNG"></inlinegraphic></link>
-  </para>
-</section>
-</para>
@@ -1,4 +1,5 @@
-# Using GTK with Wayland {#gtk-wayland}
+Title: Using GTK with Wayland
+Slug: gtk-wayland

 The GDK Wayland backend provides support for running GTK applications
 under a Wayland compositor. To run your application in this way, select
@@ -7,7 +8,7 @@ the Wayland backend by setting `GDK_BACKEND=wayland`.
 On UNIX, the Wayland backend is enabled by default, so you don't need to
 do anything special when compiling it, and everything should "just work."

-## Wayland-specific environment variables {#wayland-envar}
+## Wayland-specific environment variables

 ### WAYLAND_DISPLAY

@@ -1,4 +1,5 @@
-# Using GTK on Windows {#gtk-windows}
+Title: Using GTK on Windows
+Slug: gtk-windows

 The Windows port of GTK is an implementation of GDK (and therefore GTK)
 on top of the Win32 API. When compiling GTK on Windows, this backend is
@@ -8,7 +9,7 @@ More information about GTK on Windows, including detailed build
 instructions, binary downloads, etc, can be found
 [online](https://wiki.gnome.org/Projects/GTK/Win32).

-## Windows-specific environment variables {#win32-envar}
+## Windows-specific environment variables

 The Win32 GDK backend can be influenced with some additional environment
 variables.
@@ -22,7 +23,7 @@ If this variable is set, GTK doesn't use the Wintab API for tablet support.
 If this variable is set, GTK uses the Wintab API for tablet support.
 This is the default.

-## Windows-specific handling of cursors {#win32-cursors}
+## Windows-specific handling of cursors

 By default the "system" cursor theme is used. This makes GTK prefer cursors
 that Windows currently uses, falling back to Adwaita cursors and (as the last
@@ -1,4 +1,5 @@
-# GTK for the X Window System {#gtk-x11}
+Title: GTK for the X Window System
+Slug: gtk-x11

 On UNIX, the X backend is enabled by default, so you don't need to do anything
 special when compiling it, and everything should "just work."
@@ -7,16 +8,16 @@ To mix low-level Xlib routines into a GTK program, see
 [GDK X Window System interaction](#gdk-X-Window-System-Interaction)
 in the GDK manual.

-## X11-specific environment variables {#x11-envar}
+## X11-specific environment variables
 :
 The X11 GDK backend can be influenced with some additional environment variables.

-### GDK_SYNCHRONIZE
+### `GDK_SYNCHRONIZE`

 If set, GDK makes all X requests synchronously. This is a useful
 option for debugging, but it will slow down the performance considerably.

-### GDK_SCALE
+### `GDK_SCALE`

 Must be set to an integer, typically 2. If set, GDK will scale all
 windows by the specified factor. Scaled output is meant to be used on
@@ -24,7 +25,7 @@ high-dpi displays. Normally, GDK will pick up a suitable scale factor
 for each monitor from the display system. This environment variable
 allows to override that.

-## Understanding the X11 architecture {#gtk-X11-arch}
+## Understanding the X11 architecture

 People coming from a Windows or MacOS background often find certain
 aspects of the X Window System surprising. This section introduces
@@ -61,6 +62,7 @@ you must ask the window manager to do so on your behalf, using an
 established  [convention](http://www.freedesktop.org/standards/).

 GTK has functions for asking the window manager to do various things;
-see for example gtk_window_minimize() or gtk_window_maximize().
+see for example [method@Gtk.Window.minimize] or [method@Gtk.Window.maximize].
+
 Keep in mind that most window managers *will* ignore certain requests
 from time to time, in the interests of good user interface.
@@ -1,21 +1,9 @@
-if get_option('gtk_doc')
-  glib_prefix = dependency('glib-2.0').get_variable(pkgconfig: 'prefix', default_value: '/usr')
-  glib_docpath = join_paths(glib_prefix, 'share', 'gtk-doc', 'html')
+toml_conf = configuration_data()
+toml_conf.set('version', meson.project_version())

-  cairo_prefix = dependency('cairo-gobject').get_variable(pkgconfig: 'prefix', default_value: '/usr')
-  cairo_docpath = join_paths(cairo_prefix, 'share', 'gtk-doc', 'html', 'cairo')
+gidocgen = find_program('gi-docgen', required: get_option('gtk_doc'))

-  gdkpixbuf_prefix = dependency('gdk-pixbuf-2.0').get_variable(pkgconfig: 'prefix', default_value: '/usr')
-  gdkpixbuf_docpath = join_paths(gdkpixbuf_prefix, 'share', 'gtk-doc', 'html', 'gdk-pixbuf')
-
-  docpath = join_paths(gtk_datadir, 'gtk-doc', 'html')
-
-  version_conf = configuration_data()
-  version_conf.set('GTK_VERSION', meson.project_version())
-
-  src_dir_conf = configuration_data()
-  src_dir_conf.set('SRC_DIR', meson.source_root())
-endif
+docs_dir = gtk_datadir / 'doc/gtk4/reference'

 subdir('gdk')
 subdir('gsk')
@@ -118,9 +118,17 @@ static WidgetInfo *
 create_toggle_button (void)
 {
  GtkWidget *widget;
+  GtkWidget *button;

-  widget = gtk_toggle_button_new_with_mnemonic ("_Toggle Button");
-  gtk_toggle_button_set_active (GTK_TOGGLE_BUTTON (widget), FALSE);
+  widget = gtk_box_new (GTK_ORIENTATION_HORIZONTAL, 0);
+  gtk_box_set_homogeneous (GTK_BOX (widget), TRUE);
+  gtk_widget_add_css_class (widget, "linked");
+  button = gtk_toggle_button_new_with_label ("Toggle");
+  gtk_toggle_button_set_active (GTK_TOGGLE_BUTTON (button), TRUE);
+  gtk_box_append (GTK_BOX (widget), button);
+  button = gtk_toggle_button_new_with_label ("Button");
+  gtk_toggle_button_set_active (GTK_TOGGLE_BUTTON (button), FALSE);
+  gtk_box_append (GTK_BOX (widget), button);
  gtk_widget_set_halign (widget, GTK_ALIGN_CENTER);
  gtk_widget_set_valign (widget, GTK_ALIGN_CENTER);

@@ -132,7 +140,6 @@ create_check_button (void)
 {
  GtkWidget *widget;
  GtkWidget *button;
-  GtkWidget *group;

  widget = gtk_box_new (GTK_ORIENTATION_VERTICAL, 3);
  gtk_widget_set_halign (widget, GTK_ALIGN_CENTER);
@@ -145,6 +152,20 @@ create_check_button (void)
  button = gtk_check_button_new_with_mnemonic ("_Check Button");
  gtk_box_append (GTK_BOX (widget), button);

+  return new_widget_info ("check-button", widget, SMALL);
+}
+
+static WidgetInfo *
+create_radio_button (void)
+{
+  GtkWidget *widget;
+  GtkWidget *button;
+  GtkWidget *group;
+
+  widget = gtk_box_new (GTK_ORIENTATION_VERTICAL, 3);
+  gtk_widget_set_halign (widget, GTK_ALIGN_CENTER);
+  gtk_widget_set_valign (widget, GTK_ALIGN_CENTER);
+
  button = gtk_check_button_new_with_mnemonic ("Radio Button");
  gtk_check_button_set_active (GTK_CHECK_BUTTON (button), TRUE);
  gtk_box_append (GTK_BOX (widget), button);
@@ -154,7 +175,7 @@ create_check_button (void)
  gtk_box_append (GTK_BOX (widget), button);
  gtk_check_button_set_group (GTK_CHECK_BUTTON (button), GTK_CHECK_BUTTON (group));

-  return new_widget_info ("check-button", widget, MEDIUM);
+  return new_widget_info ("radio-button", widget, SMALL);
 }

 static WidgetInfo *
@@ -166,7 +187,7 @@ create_link_button (void)
  gtk_widget_set_halign (widget, GTK_ALIGN_CENTER);
  gtk_widget_set_valign (widget, GTK_ALIGN_CENTER);

-  return new_widget_info ("link-button", widget, SMALL);
+  return new_widget_info ("link-button", widget, MEDIUM);
 }

 static WidgetInfo *
@@ -816,6 +837,36 @@ create_message_dialog (void)
  return new_widget_info ("messagedialog", widget, ASIS);
 }

+static WidgetInfo *
+create_dialog (void)
+{
+  GtkWidget *widget;
+  GtkWidget *content;
+  GtkWidget *label;
+
+  widget = g_object_new (GTK_TYPE_DIALOG, "use-header-bar", TRUE, NULL);
+  gtk_window_set_title (GTK_WINDOW (widget), "Dialog");
+
+  gtk_dialog_add_button (GTK_DIALOG (widget), "Accept", GTK_RESPONSE_OK);
+  gtk_dialog_add_button (GTK_DIALOG (widget), "Cancel", GTK_RESPONSE_CANCEL);
+
+  gtk_dialog_set_default_response (GTK_DIALOG (widget), GTK_RESPONSE_OK);
+
+  content = gtk_dialog_get_content_area (GTK_DIALOG (widget));
+  label = gtk_label_new ("Content");
+  g_object_set (label,
+                "margin-start", 20,
+                "margin-end", 20,
+                "margin-top", 20,
+                "margin-bottom", 20,
+                NULL);
+  gtk_widget_set_hexpand (label, TRUE);
+  gtk_widget_set_halign (label, GTK_ALIGN_CENTER);
+  gtk_box_append (GTK_BOX (content), label);
+
+  return new_widget_info ("dialog", widget, ASIS);
+}
+
 static WidgetInfo *
 create_about_dialog (void)
 {
@@ -827,19 +878,27 @@ create_about_dialog (void)
    "and many more...",
    NULL
  };
+  GFile *file;
+  GdkTexture *logo;
+
+  file = g_file_new_for_path ("docs/tools/gtk-logo.png");
+  logo = gdk_texture_new_from_file (file, NULL);

  widget = gtk_about_dialog_new ();
  g_object_set (widget,
                "program-name", "GTK Code Demos",
                "version", PACKAGE_VERSION,
-                "copyright", "© 1997-2013 The GTK Team",
+                "copyright", "© 1997-2021 The GTK Team",
                "website", "http://www.gtk.org",
                "comments", "Program to demonstrate GTK functions.",
-                "logo-icon-name", "help-about",
+                "logo", logo,
                "title", "About GTK Code Demos",
                "authors", authors,
 		NULL);
-  gtk_window_set_icon_name (GTK_WINDOW (widget), "help-about");
+
+  g_object_unref (logo);
+  g_object_unref (file);
+
  return new_widget_info ("aboutdialog", widget, ASIS);
 }

@@ -2094,10 +2153,12 @@ get_all_widgets (void)
  retval = g_list_prepend (retval, create_about_dialog ());
  retval = g_list_prepend (retval, create_button ());
  retval = g_list_prepend (retval, create_check_button ());
+  retval = g_list_prepend (retval, create_radio_button ());
  retval = g_list_prepend (retval, create_color_button ());
  retval = g_list_prepend (retval, create_combo_box ());
  retval = g_list_prepend (retval, create_combo_box_entry ());
  retval = g_list_prepend (retval, create_combo_box_text ());
+  retval = g_list_prepend (retval, create_dialog ());
  retval = g_list_prepend (retval, create_entry ());
  retval = g_list_prepend (retval, create_font_button ());
  retval = g_list_prepend (retval, create_frame ());
@@ -235,7 +235,7 @@ static void
 parse_all_input (GdkBroadwayServer *server)
 {
  guint8 *p, *end;
-  size_t size;
+  guint32 size;
  BroadwayReply *reply;

  p = server->recv_buffer;
@@ -47,27 +47,6 @@
 #include <fribidi.h>


-/**
- * SECTION:general
- * @Short_description: Library initialization and versioning
- * @Title: General
- *
- * This section describes miscellaneous macros and utility functions
- * related to library versioning, as well as deprecation facilities.
- *
- * The GDK and GTK headers annotate deprecated APIs in a way that produces
- * compiler warnings if these deprecated APIs are used. The warnings
- * can be turned off by defining the macro %GDK_DISABLE_DEPRECATION_WARNINGS
- * before including the glib.h header.
- *
- * GDK and GTK also provide support for building applications against
- * defined subsets of deprecated or new APIs. Define the macro
- * %GDK_VERSION_MIN_REQUIRED to specify up to what version
- * you want to receive warnings about deprecated APIs. Define the
- * macro %GDK_VERSION_MAX_ALLOWED to specify the newest version
- * whose API you want to use.
- */
-
 /**
 * GDK_WINDOWING_X11:
 *
@@ -26,18 +26,17 @@


 /**
- * SECTION:gdkapplaunchcontext
- * @Short_description: Startup notification for applications
- * @Title: Application launching
+ * GdkAppLaunchContext:
 *
- * GdkAppLaunchContext is an implementation of #GAppLaunchContext that
- * handles launching an application in a graphical context. It provides
- * startup notification and allows to launch applications on a specific
- * screen or workspace.
+ * `GdkAppLaunchContext` handles launching an application in a graphical context.
+ *
+ * It is an implementation of `GAppLaunchContext` that provides startup
+ * notification and allows to launch applications on a specific screen
+ * or workspace.
 *
 * ## Launching an application
 *
- * |[<!-- language="C" -->
+ * ```c
 * GdkAppLaunchContext *context;
 *
 * context = gdk_display_get_app_launch_context (display);
@@ -49,14 +48,7 @@
 *   g_warning ("Launching failed: %s\n", error->message);
 *
 * g_object_unref (context);
- * ]|
- */
-
-/**
- * GdkAppLaunchContext:
- *
- * The GdkAppLaunchContext struct contains only private fields
- * and should not be accessed directly.
+ * ```
 */

 static void    gdk_app_launch_context_finalize    (GObject           *object);
@@ -129,6 +121,11 @@ gdk_app_launch_context_class_init (GdkAppLaunchContextClass *klass)
  context_class->get_startup_notify_id = gdk_app_launch_context_get_startup_notify_id;
  context_class->launch_failed = gdk_app_launch_context_launch_failed;

+  /**
+   * GdkAppLaunchContext:display: (attributes org.gtk.Property.get=gdk_app_launch_context_get_display)
+   *
+   * The display that the `GdkAppLaunchContext` is on.
+   */
  g_object_class_install_property (gobject_class, PROP_DISPLAY,
    g_param_spec_object ("display", P_("Display"), P_("Display"),
                         GDK_TYPE_DISPLAY,
@@ -174,10 +171,10 @@ gdk_app_launch_context_get_display_name (GAppLaunchContext *context,
 }

 /**
- * gdk_app_launch_context_get_display:
- * @context: a #GdkAppLaunchContext
+ * gdk_app_launch_context_get_display: (attributes org.gtk.Method.get_property=display)
+ * @context: a `GdkAppLaunchContext`
 *
- * Gets the #GdkDisplay that @context is for.
+ * Gets the `GdkDisplay` that @context is for.
 *
 * Returns: (transfer none): the display of @context
 */
@@ -191,11 +188,12 @@ gdk_app_launch_context_get_display (GdkAppLaunchContext *context)

 /**
 * gdk_app_launch_context_set_desktop:
- * @context: a #GdkAppLaunchContext
+ * @context: a `GdkAppLaunchContext`
 * @desktop: the number of a workspace, or -1
 *
- * Sets the workspace on which applications will be launched when
- * using this context when running under a window manager that
+ * Sets the workspace on which applications will be launched.
+ *
+ * This only works when running under a window manager that
 * supports multiple workspaces, as described in the
 * [Extended Window Manager Hints](http://www.freedesktop.org/Standards/wm-spec).
 *
@@ -214,11 +212,13 @@ gdk_app_launch_context_set_desktop (GdkAppLaunchContext *context,

 /**
 * gdk_app_launch_context_set_timestamp:
- * @context: a #GdkAppLaunchContext
+ * @context: a `GdkAppLaunchContext`
 * @timestamp: a timestamp
 *
- * Sets the timestamp of @context. The timestamp should ideally
- * be taken from the event that triggered the launch.
+ * Sets the timestamp of @context.
+ *
+ * The timestamp should ideally be taken from the event that
+ * triggered the launch.
 *
 * Window managers can use this information to avoid moving the
 * focus to the newly launched application when the user is busy
@@ -236,7 +236,7 @@ gdk_app_launch_context_set_timestamp (GdkAppLaunchContext *context,

 /**
 * gdk_app_launch_context_set_icon:
- * @context: a #GdkAppLaunchContext
+ * @context: a `GdkAppLaunchContext`
 * @icon: (allow-none): a #GIcon, or %NULL
 *
 * Sets the icon for applications that are launched with this
@@ -245,7 +245,7 @@ gdk_app_launch_context_set_timestamp (GdkAppLaunchContext *context,
 * Window Managers can use this information when displaying startup
 * notification.
 *
- * See also gdk_app_launch_context_set_icon_name().
+ * See also [method@Gdk.AppLaunchContext.set_icon_name].
 */
 void
 gdk_app_launch_context_set_icon (GdkAppLaunchContext *context,
@@ -266,16 +266,17 @@ gdk_app_launch_context_set_icon (GdkAppLaunchContext *context,

 /**
 * gdk_app_launch_context_set_icon_name:
- * @context: a #GdkAppLaunchContext
+ * @context: a `GdkAppLaunchContext`
 * @icon_name: (allow-none): an icon name, or %NULL
 *
 * Sets the icon for applications that are launched with this context.
+ *
 * The @icon_name will be interpreted in the same way as the Icon field
- * in desktop files. See also gdk_app_launch_context_set_icon().
+ * in desktop files. See also [method@Gdk.AppLaunchContext.set_icon()].
 *
 * If both @icon and @icon_name are set, the @icon_name takes priority.
 * If neither @icon or @icon_name is set, the icon is taken from either
- * the file that is passed to launched application or from the #GAppInfo
+ * the file that is passed to launched application or from the `GAppInfo`
 * for the launched application itself.
 */
 void
@@ -23,22 +23,6 @@

 #include <math.h>

-/**
- * SECTION:cairo_interaction
- * @Short_description: Functions to support using cairo
- * @Title: Cairo Interaction
- *
- * [Cairo](http://cairographics.org) is a graphics
- * library that supports vector graphics and image compositing that
- * can be used with GDK and GTK.
- *
- * GDK does not wrap the cairo API, instead it allows to create cairo
- * contexts which can be used to draw on #GdkSurfaces. Additional
- * functions allow use #GdkRectangles with cairo and to use #GdkRGBAs,
- * #GdkPixbufs and #GdkSurfaces as sources for drawing operations.
- */
-
-
 /**
 * gdk_cairo_set_source_rgba:
 * @cr: a cairo context
@@ -297,13 +281,13 @@ _gdk_cairo_surface_extents (cairo_surface_t *surface,
 * gdk_cairo_region_create_from_surface:
 * @surface: a cairo surface
 *
- * Creates region that describes covers the area where the given
+ * Creates region that covers the area where the given
 * @surface is more than 50% opaque.
 *
 * This function takes into account device offsets that might be
 * set with cairo_surface_set_device_offset().
 *
- * Returns: A #cairo_region_t; must be freed with cairo_region_destroy()
+ * Returns: A `cairo_region_t`; must be freed with cairo_region_destroy()
 */
 cairo_region_t *
 gdk_cairo_region_create_from_surface (cairo_surface_t *surface)
@@ -27,24 +27,15 @@
 #include "gdkcairo.h"
 #include "gdkinternals.h"

-/**
- * SECTION:gdkcairocontext
- * @Title: GdkCairoContext
- * @Short_description: Cairo draw context
- *
- * #GdkCairoContext is an object representing the platform-specific
- * draw context.
- *
- * #GdkCairoContexts are created for a #GdkDisplay using
- * gdk_surface_create_cairo_context(), and the context can then be used
- * to draw on that #GdkSurface.
- */
-
 /**
 * GdkCairoContext:
 *
- * The GdkCairoContext struct contains only private fields and should not
- * be accessed directly.
+ * `GdkCairoContext` is an object representing the platform-specific
+ * draw context.
+ *
+ * `GdkCairoContext`s are created for a surface using
+ * [method@Gdk.Surface.create_cairo_context], and the context can then be used
+ * to draw on that surface.
 */

 typedef struct _GdkCairoContextPrivate GdkCairoContextPrivate;
@@ -70,15 +61,17 @@ gdk_cairo_context_init (GdkCairoContext *self)
 * gdk_cairo_context_cairo_create:
 * @self: a #GdkCairoContext that is currently drawing
 *
- * Retrieves a Cairo context to be used to draw on the #GdkSurface
- * of @context. A call to gdk_draw_context_begin_frame() with this
+ * Retrieves a Cairo context to be used to draw on the `GdkSurface`
+ * of @context.
+ *
+ * A call to [method@Gdk.DrawContext.begin_frame] with this
 * @context must have been done or this function will return %NULL.
 *
 * The returned context is guaranteed to be valid until
- * gdk_draw_context_end_frame() is called.
+ * [method@Gdk.DrawContext.end_frame] is called.
 *
 * Returns: (transfer full) (nullable): a Cairo context to be used
- *   to draw the contents of the #GdkSurface. %NULL is returned
+ *   to draw the contents of the `GdkSurface`. %NULL is returned
 *   when @context is not drawing.
 */
 cairo_t *
@@ -32,34 +32,26 @@

 #include <gobject/gvaluecollector.h>

-/**
- * SECTION:gdkclipboard
- * @Short_description: Share data between applications for Copy-and-Paste
- * @Title: Clipboards
- * @See_also: #GdkContentProvider, #GdkContentFormats
- *
- * The #GdkClipboard object represents a clipboard of data shared
- * between different applications or between different parts of
- * the same application.
- *
- * To get a GdkClipboard object, use gdk_display_get_clipboard() or
- * gdk_display_get_primary_clipboard(). You can find out about the data that
- * is currently available in a clipboard using gdk_clipboard_get_formats().
- *
- * To make text or image data available in a clipboard, use gdk_clipboard_set_text() or
- * gdk_clipboard_set_texture(). For other data, you can use gdk_clipboard_set_content(),
- * which takes a #GdkContentProvider object.
- *
- * To read textual or image data from a clipboard, use gdk_clipboard_read_text_async() or
- * gdk_clipboard_read_texture_async(). For other data, use gdk_clipboard_read_async(),
- * which provides a #GInputStream object.
- */
-
 /**
 * GdkClipboard:
 *
- * The GdkClipboard struct contains only private fields and should not be
- * accessed directly.
+ * The `GdkClipboard` object represents data shared between applications or
+ * inside an application.
+ *
+ * To get a `GdkClipboard` object, use [method@Gdk.Display.get_clipboard] or
+ * [method@Gdk.Display.get_primary_clipboard]. You can find out about the data
+ * that is currently available in a clipboard using
+ * [method@Gdk.Clipboard.get_formats].
+ *
+ * To make text or image data available in a clipboard, use
+ * [method@Gdk.Clipboard.set_text] or [method@Gdk.Clipboard.set_texture].
+ * For other data, you can use [method@Gdk.Clipboard.set_content], which
+ * takes a [class@Gdk.ContentProvider] object.
+ *
+ * To read textual or image data from a clipboard, use
+ * [method@Gdk.Clipboard.read_text_async] or
+ * [method@Gdk.Clipboard.read_texture_async]. For other data, use
+ * [method@Gdk.Clipboard.read_async], which provides a `GInputStream` object.
 */

 typedef struct _GdkClipboardPrivate GdkClipboardPrivate;
@@ -360,9 +352,9 @@ gdk_clipboard_class_init (GdkClipboardClass *class)
  class->read_finish = gdk_clipboard_read_local_finish;

  /**
-   * GdkClipboard:display:
+   * GdkClipboard:display: (attributes org.gtk.Property.get=gdk_clipboard_get_display)
   *
-   * The #GdkDisplay that the clipboard belongs to.
+   * The `GdkDisplay` that the clipboard belongs to.
   */
  properties[PROP_DISPLAY] =
    g_param_spec_object ("display",
@@ -375,7 +367,7 @@ gdk_clipboard_class_init (GdkClipboardClass *class)
                         G_PARAM_EXPLICIT_NOTIFY);

  /**
-   * GdkClipboard:formats:
+   * GdkClipboard:formats: (attributes org.gtk.Property.get=gdk_clipboard_get_formats)
   *
   * The possible formats that the clipboard can provide its data in.
   */
@@ -389,7 +381,7 @@ gdk_clipboard_class_init (GdkClipboardClass *class)
                        G_PARAM_EXPLICIT_NOTIFY);

  /**
-   * GdkClipboard:local:
+   * GdkClipboard:local: (attributes org.gtk.Property.get=gdk_clipboard_is_local)
   *
   * %TRUE if the contents of the clipboard are owned by this process.
   */
@@ -403,9 +395,9 @@ gdk_clipboard_class_init (GdkClipboardClass *class)
                          G_PARAM_EXPLICIT_NOTIFY);

  /**
-   * GdkClipboard:content:
+   * GdkClipboard:content: (attributes org.gtk.Property.get=gdk_clipboard_get_content)
   *
-   * The #GdkContentProvider or %NULL if the clipboard is empty or contents are
+   * The `GdkContentProvider` or %NULL if the clipboard is empty or contents are
   * provided otherwise.
   */
  properties[PROP_CONTENT] =
@@ -421,7 +413,7 @@ gdk_clipboard_class_init (GdkClipboardClass *class)
   * GdkClipboard::changed:
   * @clipboard: the object on which the signal was emitted
   *
-   * The ::changed signal is emitted when the clipboard changes ownership.
+   * Emitted when the clipboard changes ownership.
   */
  signals[CHANGED] =
    g_signal_new ("changed",
@@ -444,13 +436,13 @@ gdk_clipboard_init (GdkClipboard *clipboard)
 }

 /**
- * gdk_clipboard_get_display:
- * @clipboard: a #GdkClipboard
+ * gdk_clipboard_get_display: (attributes org.gtk.Method.get_property=display)
+ * @clipboard: a `GdkClipboard`
 *
- * Gets the #GdkDisplay that the clipboard was created for.
+ * Gets the `GdkDisplay` that the clipboard was created for.
 *
- * Returns: (transfer none): a #GdkDisplay
- **/
+ * Returns: (transfer none): a `GdkDisplay`
+ */
 GdkDisplay *
 gdk_clipboard_get_display (GdkClipboard *clipboard)
 {
@@ -462,13 +454,13 @@ gdk_clipboard_get_display (GdkClipboard *clipboard)
 }

 /**
- * gdk_clipboard_get_formats:
- * @clipboard: a #GdkClipboard
+ * gdk_clipboard_get_formats: (attributes org.gtk.Method.get_property=formats)
+ * @clipboard: a `GdkClipboard`
 *
 * Gets the formats that the clipboard can provide its current contents in.
 *
 * Returns: (transfer none): The formats of the clipboard
- **/
+ */
 GdkContentFormats *
 gdk_clipboard_get_formats (GdkClipboard *clipboard)
 {
@@ -480,17 +472,19 @@ gdk_clipboard_get_formats (GdkClipboard *clipboard)
 }

 /**
- * gdk_clipboard_is_local:
- * @clipboard: a #GdkClipboard
+ * gdk_clipboard_is_local: (attributes org.gtk.Method.get_property=local)
+ * @clipboard: a `GdkClipboard`
 *
- * Returns if the clipboard is local. A clipboard is considered local if it was
- * last claimed by the running application.
+ * Returns if the clipboard is local.
 *
- * Note that gdk_clipboard_get_content() may return %NULL even on a local
- * clipboard. In this case the clipboard is empty.
+ * A clipboard is considered local if it was last claimed
+ * by the running application.
+ *
+ * Note that [method@Gdk.Clipboard.get_content] may return %NULL
+ * even on a local clipboard. In this case the clipboard is empty.
 *
 * Returns: %TRUE if the clipboard is local
- **/
+ */
 gboolean
 gdk_clipboard_is_local (GdkClipboard *clipboard)
 {
@@ -502,16 +496,17 @@ gdk_clipboard_is_local (GdkClipboard *clipboard)
 }

 /**
- * gdk_clipboard_get_content:
- * @clipboard: a #GdkClipboard
+ * gdk_clipboard_get_content: (attributes org.gtk.Method.get_property=content)
+ * @clipboard: a `GdkClipboard`
 *
- * Returns the #GdkContentProvider currently set on @clipboard. If the
- * @clipboard is empty or its contents are not owned by the current process,
- * %NULL will be returned.
+ * Returns the `GdkContentProvider` currently set on @clipboard.
+ *
+ * If the @clipboard is empty or its contents are not owned by the
+ * current process, %NULL will be returned.
 *
 * Returns: (transfer none) (nullable): The content of a clipboard or %NULL
 *     if the clipboard does not maintain any content.
- **/
+ */
 GdkContentProvider *
 gdk_clipboard_get_content (GdkClipboard *clipboard)
 {
@@ -524,20 +519,26 @@ gdk_clipboard_get_content (GdkClipboard *clipboard)

 /**
 * gdk_clipboard_store_async:
- * @clipboard: a #GdkClipboard
- * @io_priority: the [I/O priority][io-priority]
- *     of the request. 
- * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
+ * @clipboard: a `GdkClipboard`
+ * @io_priority: the I/O priority of the request.
+ * @cancellable: (nullable): optional `GCancellable` object, %NULL to ignore.
 * @callback: (scope async): callback to call when the request is satisfied
 * @user_data: (closure): the data to pass to callback function
 *
- * Asynchronously instructs the @clipboard to store its contents remotely to
- * preserve them for later usage. If the clipboard is not local, this function
- * does nothing but report success.
+ * Asynchronously instructs the @clipboard to store its contents remotely.
 *
- * This function is called automatically when gtk_main() or #GtkApplication
- * exit, so you likely don't need to call it.
- **/
+ * If the clipboard is not local, this function does nothing but report success.
+ *
+ * The @callback must call [method@Gdk.Clipboard.store_finish].
+ *
+ * The purpose of this call is to preserve clipboard contents beyond the
+ * lifetime of an application, so this function is typically called on
+ * exit. Depending on the platform, the functionality may not be available
+ * unless a "clipboard manager" is running.
+ *
+ * This function is called automatically when a [class@Gtk.Application] is
+ * shut down, so you likely don't need to call it.
+ */
 void
 gdk_clipboard_store_async (GdkClipboard        *clipboard,
                           int                  io_priority,
@@ -571,15 +572,16 @@ gdk_clipboard_store_async (GdkClipboard        *clipboard,

 /**
 * gdk_clipboard_store_finish:
- * @clipboard: a #GdkClipboard
- * @result: a #GAsyncResult
- * @error: a #GError location to store the error occurring, or %NULL to 
- * ignore.
+ * @clipboard: a `GdkClipboard`
+ * @result: a `GAsyncResult`
+ * @error: a `GError` location to store the error occurring, or %NULL to ignore.
 *
- * Finishes an asynchronous clipboard store started with gdk_clipboard_store_async().
+ * Finishes an asynchronous clipboard store.
+ *
+ * See [method@Gdk.Clipboard.store_async].
 *
 * Returns: %TRUE if storing was successful.
- **/
+ */
 gboolean
 gdk_clipboard_store_finish (GdkClipboard  *clipboard,
                            GAsyncResult  *result,
@@ -632,22 +634,22 @@ gdk_clipboard_read_internal (GdkClipboard        *clipboard,

 /**
 * gdk_clipboard_read_async:
- * @clipboard: a #GdkClipboard
+ * @clipboard: a `GdkClipboard`
 * @mime_types: a %NULL-terminated array of mime types to choose from
- * @io_priority: the [I/O priority][io-priority]
- * of the request. 
- * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
+ * @io_priority: the I/O priority of the request
+ * @cancellable: (nullable): optional `GCancellable` object, %NULL to ignore.
 * @callback: (scope async): callback to call when the request is satisfied
 * @user_data: (closure): the data to pass to callback function
 *
 * Asynchronously requests an input stream to read the @clipboard's
- * contents from. When the operation is finished @callback will be called. 
- * You can then call gdk_clipboard_read_finish() to get the result of the 
- * operation.
+ * contents from.
+ *
+ * When the operation is finished @callback will be called. You must then
+ * call [method@Gdk.Clipboard.read_finish] to get the result of the operation.
 *
 * The clipboard will choose the most suitable mime type from the given list
- * to fulfill the request, preferring the ones listed first. 
- **/
+ * to fulfill the request, preferring the ones listed first.
+ */
 void
 gdk_clipboard_read_async (GdkClipboard        *clipboard,
                          const char         **mime_types,
@@ -672,17 +674,18 @@ gdk_clipboard_read_async (GdkClipboard        *clipboard,

 /**
 * gdk_clipboard_read_finish:
- * @clipboard: a #GdkClipboard
- * @result: a #GAsyncResult
+ * @clipboard: a `GdkClipboard`
+ * @result: a `GAsyncResult`
 * @out_mime_type: (out) (allow-none) (transfer none): pointer to store
 *     the chosen mime type in or %NULL
- * @error: a #GError location to store the error occurring, or %NULL to 
- * ignore.
+ * @error: a `GError` location to store the error occurring, or %NULL to ignore.
 *
- * Finishes an asynchronous clipboard read started with gdk_clipboard_read_async().
+ * Finishes an asynchronous clipboard read.
 *
- * Returns: (transfer full) (nullable): a #GInputStream or %NULL on error.
- **/
+ * See [method@Gdk.Clipboard.read_async].
+ *
+ * Returns: (transfer full) (nullable): a `GInputStream` or %NULL on error.
+ */
 GInputStream *
 gdk_clipboard_read_finish (GdkClipboard  *clipboard,
                           GAsyncResult  *result,
@@ -827,23 +830,23 @@ gdk_clipboard_read_value_internal (GdkClipboard        *clipboard,

 /**
 * gdk_clipboard_read_value_async:
- * @clipboard: a #GdkClipboard
- * @type: a #GType to read
- * @io_priority: the [I/O priority][io-priority]
- *     of the request. 
+ * @clipboard: a `GdkClipboard`
+ * @type: a `GType` to read
+ * @io_priority: the I/O priority of the request
 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
 * @callback: (scope async): callback to call when the request is satisfied
 * @user_data: (closure): the data to pass to callback function
 *
 * Asynchronously request the @clipboard contents converted to the given
- * @type. When the operation is finished @callback will be called. 
- * You can then call gdk_clipboard_read_value_finish() to get the resulting
- * #GValue.
+ * @type.
 *
- * For local clipboard contents that are available in the given #GType, the
- * value will be copied directly. Otherwise, GDK will try to use
- * gdk_content_deserialize_async() to convert the clipboard's data.
- **/
+ * When the operation is finished @callback will be called. You must then call
+ * [method@Gdk.Clipboard.read_value_finish] to get the resulting `GValue`.
+ *
+ * For local clipboard contents that are available in the given `GType`,
+ * the value will be copied directly. Otherwise, GDK will try to use
+ * [func@content_deserialize_async] to convert the clipboard's data.
+ */
 void
 gdk_clipboard_read_value_async (GdkClipboard        *clipboard,
                                GType                type,
@@ -867,16 +870,16 @@ gdk_clipboard_read_value_async (GdkClipboard        *clipboard,

 /**
 * gdk_clipboard_read_value_finish:
- * @clipboard: a #GdkClipboard
- * @result: a #GAsyncResult
- * @error: a #GError location to store the error occurring, or %NULL to 
- * ignore.
+ * @clipboard: a `GdkClipboard`
+ * @result: a `GAsyncResult`
+ * @error: a GError` location to store the error occurring, or %NULL to ignore
 *
- * Finishes an asynchronous clipboard read started with
- * gdk_clipboard_read_value_async().
+ * Finishes an asynchronous clipboard read.
 *
- * Returns: (transfer none): a #GValue containing the result.
- **/
+ * See [method@Gdk.Clipboard.read_value_async].
+ *
+ * Returns: (transfer none): a `GValue` containing the result.
+ */
 const GValue *
 gdk_clipboard_read_value_finish (GdkClipboard  *clipboard,
                                 GAsyncResult  *result,
@@ -891,19 +894,20 @@ gdk_clipboard_read_value_finish (GdkClipboard  *clipboard,

 /**
 * gdk_clipboard_read_texture_async:
- * @clipboard: a #GdkClipboard
- * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
+ * @clipboard: a `GdkClipboard`
+ * @cancellable: (nullable): optional `GCancellable` object, %NULL to ignore.
 * @callback: (scope async): callback to call when the request is satisfied
 * @user_data: (closure): the data to pass to callback function
 *
- * Asynchronously request the @clipboard contents converted to a #GdkPixbuf.
- * When the operation is finished @callback will be called. You can then
- * call gdk_clipboard_read_texture_finish() to get the result.
+ * Asynchronously request the @clipboard contents converted to a `GdkPixbuf`.
 *
- * This is a simple wrapper around gdk_clipboard_read_value_async(). Use
- * that function or gdk_clipboard_read_async() directly if you need more
- * control over the operation.
- **/
+ * When the operation is finished @callback will be called. You must then
+ * call [method@Gdk.Clipboard.read_texture_finish] to get the result.
+ *
+ * This is a simple wrapper around [method@Gdk.Clipboard.read_value_async].
+ * Use that function or [methos@Gdk.Clipboard.read_async] directly if you
+ * need more control over the operation.
+ */
 void
 gdk_clipboard_read_texture_async (GdkClipboard        *clipboard,
                                  GCancellable        *cancellable,
@@ -925,16 +929,16 @@ gdk_clipboard_read_texture_async (GdkClipboard        *clipboard,

 /**
 * gdk_clipboard_read_texture_finish:
- * @clipboard: a #GdkClipboard
- * @result: a #GAsyncResult
- * @error: a #GError location to store the error occurring, or %NULL to 
- * ignore.
+ * @clipboard: a `GdkClipboard`
+ * @result: a `GAsyncResult`
+ * @error: a `GError` location to store the error occurring, or %NULL to ignore
 *
- * Finishes an asynchronous clipboard read started with
- * gdk_clipboard_read_texture_async().
+ * Finishes an asynchronous clipboard read.
 *
- * Returns: (transfer full) (nullable): a new #GdkTexture or %NULL on error.
- **/
+ * See [method@Gdk.Clipboard.read_texture_async].
+ *
+ * Returns: (transfer full) (nullable): a new `GdkTexture` or %NULL on error
+ */
 GdkTexture *
 gdk_clipboard_read_texture_finish (GdkClipboard  *clipboard,
                                   GAsyncResult  *result,
@@ -955,19 +959,20 @@ gdk_clipboard_read_texture_finish (GdkClipboard  *clipboard,

 /**
 * gdk_clipboard_read_text_async:
- * @clipboard: a #GdkClipboard
- * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
+ * @clipboard: a `GdkClipboard`
+ * @cancellable: (nullable): optional `GCancellable` object, %NULL to ignore
 * @callback: (scope async): callback to call when the request is satisfied
 * @user_data: (closure): the data to pass to callback function
 *
 * Asynchronously request the @clipboard contents converted to a string.
- * When the operation is finished @callback will be called. You can then
- * call gdk_clipboard_read_text_finish() to get the result.
 *
- * This is a simple wrapper around gdk_clipboard_read_value_async(). Use
- * that function or gdk_clipboard_read_async() directly if you need more
- * control over the operation.
- **/
+ * When the operation is finished @callback will be called. You must then
+ * call [method@Gdk.Clipboard.read_text_finish] to get the result.
+ *
+ * This is a simple wrapper around [method@Gdk.Clipboard.read_value_async].
+ * Use that function or [method@Gdk.Clipboard.read_async] directly if you
+ * need more control over the operation.
+ */
 void
 gdk_clipboard_read_text_async (GdkClipboard        *clipboard,
                               GCancellable        *cancellable,
@@ -989,16 +994,16 @@ gdk_clipboard_read_text_async (GdkClipboard        *clipboard,

 /**
 * gdk_clipboard_read_text_finish:
- * @clipboard: a #GdkClipboard
- * @result: a #GAsyncResult
- * @error: a #GError location to store the error occurring, or %NULL to 
- * ignore.
+ * @clipboard: a `GdkClipboard`
+ * @result: a `GAsyncResult`
+ * @error: a `GError` location to store the error occurring, or %NULL to ignore
 *
- * Finishes an asynchronous clipboard read started with
- * gdk_clipboard_read_text_async().
+ * Finishes an asynchronous clipboard read.
 *
- * Returns: (transfer full) (nullable): a new string or %NULL on error.
- **/
+ * See [method@Gdk.Clipboard.read_text_async].
+ *
+ * Returns: (transfer full) (nullable): a new string or %NULL on error
+ */
 char *
 gdk_clipboard_read_text_finish (GdkClipboard  *clipboard,
                                GAsyncResult  *result,
@@ -1188,13 +1193,14 @@ gdk_clipboard_claim_remote (GdkClipboard      *clipboard,

 /**
 * gdk_clipboard_set_content:
- * @clipboard: a #GdkClipboard
+ * @clipboard: a `GdkClipboard`
 * @provider: (transfer none) (allow-none): the new contents of @clipboard or
 *     %NULL to clear the clipboard
 *
- * Sets a new content provider on @clipboard. The clipboard will claim the
- * #GdkDisplay's resources and advertise these new contents to other
- * applications.
+ * Sets a new content provider on @clipboard.
+ *
+ * The clipboard will claim the `GdkDisplay`'s resources and advertise
+ * these new contents to other applications.
 *
 * In the rare case of a failure, this function will return %FALSE. The
 * clipboard will then continue reporting its old contents and ignore
@@ -1205,7 +1211,7 @@ gdk_clipboard_claim_remote (GdkClipboard      *clipboard,
 * transfer the contents and then request that format from @provider.
 *
 * Returns: %TRUE if setting the clipboard succeeded
- **/
+ */
 gboolean
 gdk_clipboard_set_content (GdkClipboard       *clipboard,
                           GdkContentProvider *provider)
@@ -1242,16 +1248,19 @@ gdk_clipboard_set_content (GdkClipboard       *clipboard,

 /**
 * gdk_clipboard_set:
- * @clipboard: a #GdkClipboard
+ * @clipboard: a `GdkClipboard`
 * @type: type of value to set
 * @...: value contents conforming to @type
 *
- * Sets the clipboard to contain the value collected from the given
- * varargs.
- **/
+ * Sets the clipboard to contain the value collected from the given varargs.
+ *
+ * ```c
+ * gdk_clipboard_set (clipboard, GTK_TYPE_TEXT_BUFFER, buffer);
+ * ```
+ */
 void
-gdk_clipboard_set (GdkClipboard          *clipboard,
-                   GType                  type,
+gdk_clipboard_set (GdkClipboard *clipboard,
+                   GType         type,
                   ...)
 {
  va_list args;
@@ -1265,13 +1274,12 @@ gdk_clipboard_set (GdkClipboard          *clipboard,

 /**
 * gdk_clipboard_set_valist: (skip)
- * @clipboard: a #GdkClipboard
+ * @clipboard: a `GdkClipboard`
 * @type: type of value to set
 * @args: varargs containing the value of @type
 *
- * Sets the clipboard to contain the value collected from the given
- * @args.
- **/
+ * Sets the clipboard to contain the value collected from the given @args.
+ */
 void
 gdk_clipboard_set_valist (GdkClipboard *clipboard,
                          GType         type,
@@ -1301,11 +1309,11 @@ gdk_clipboard_set_valist (GdkClipboard *clipboard,

 /**
 * gdk_clipboard_set_value: (rename-to gdk_clipboard_set)
- * @clipboard: a #GdkClipboard
- * @value: a #GValue to set
+ * @clipboard: a `GdkClipboard`
+ * @value: a `GValue` to set
 *
 * Sets the @clipboard to contain the given @value.
- **/
+ */
 void
 gdk_clipboard_set_value (GdkClipboard *clipboard,
                         const GValue *value)
@@ -1323,11 +1331,11 @@ gdk_clipboard_set_value (GdkClipboard *clipboard,

 /**
 * gdk_clipboard_set_text: (skip)
- * @clipboard: a #GdkClipboard
+ * @clipboard: a `GdkClipboard`
 * @text: Text to put into the clipboard
 *
 * Puts the given @text into the clipboard.
- **/
+ */
 void
 gdk_clipboard_set_text (GdkClipboard *clipboard,
                        const char   *text)
@@ -1339,11 +1347,11 @@ gdk_clipboard_set_text (GdkClipboard *clipboard,

 /**
 * gdk_clipboard_set_texture: (skip)
- * @clipboard: a #GdkClipboard
- * @texture: a #GdkTexture to put into the clipboard
+ * @clipboard: a `GdkClipboard`
+ * @texture: a `GdkTexture` to put into the clipboard
 *
 * Puts the given @texture into the clipboard.
- **/
+ */
 void
 gdk_clipboard_set_texture (GdkClipboard *clipboard,
                           GdkTexture   *texture)
@@ -1353,4 +1361,3 @@ gdk_clipboard_set_texture (GdkClipboard *clipboard,

  gdk_clipboard_set (clipboard, GDK_TYPE_TEXTURE, texture);
 }
-
@@ -30,13 +30,19 @@


 /**
- * SECTION:gdkcontentdeserializer
- * @Short_description: Deserialize content for transfer
- * @Title: GdkContentDeserializer
- * @See_also: #GdkContentSerializer
+ * GdkContentDeserializer:
 *
- * A GdkContentDeserializer is used to deserialize content received via
+ * A `GdkContentDeserializer` is used to deserialize content received via
 * inter-application data transfers.
+ *
+ * The `GdkContentDeserializer` transforms serialized content that is
+ * identified by a mime type into an object identified by a GType.
+ *
+ * GTK provides serializers and deserializers for common data types
+ * such as text, colors, images or file lists. To register your own
+ * deserialization functions, use [func@content_register_deserializer].
+ *
+ * Also see [class@Gdk.ContentSerializer].
 */

 typedef struct _Deserializer Deserializer;
@@ -166,7 +172,7 @@ gdk_content_deserializer_run (const char                *mime_type,

 /**
 * gdk_content_deserializer_get_mime_type:
- * @deserializer: a #GdkContentDeserializer
+ * @deserializer: a `GdkContentDeserializer`
 *
 * Gets the mime type to deserialize from.
 *
@@ -182,7 +188,7 @@ gdk_content_deserializer_get_mime_type (GdkContentDeserializer *deserializer)

 /**
 * gdk_content_deserializer_get_gtype:
- * @deserializer: a #GdkContentDeserializer
+ * @deserializer: a `GdkContentDeserializer`
 *
 * Gets the GType to create an instance of.
 *
@@ -198,11 +204,11 @@ gdk_content_deserializer_get_gtype (GdkContentDeserializer *deserializer)

 /**
 * gdk_content_deserializer_get_value:
- * @deserializer: a #GdkContentDeserializer
+ * @deserializer: a `GdkContentDeserializer`
 *
- * Gets the #GValue to store the deserialized object in.
+ * Gets the `GValue` to store the deserialized object in.
 *
- * Returns: (transfer none): the #GValue for the current operation
+ * Returns: (transfer none): the `GValue` for the current operation
 */
 GValue *
 gdk_content_deserializer_get_value (GdkContentDeserializer *deserializer)
@@ -214,9 +220,11 @@ gdk_content_deserializer_get_value (GdkContentDeserializer *deserializer)

 /**
 * gdk_content_deserializer_get_input_stream:
- * @deserializer: a #GdkContentDeserializer
+ * @deserializer: a `GdkContentDeserializer`
 *
- * Gets the input stream that was passed to gdk_content_deserialize_async().
+ * Gets the input stream for the current operation.
+ *
+ * This is the stream that was passed to [func@content_deserialize_async].
 *
 * Returns: (transfer none): the input stream for the current operation
 */
@@ -230,11 +238,13 @@ gdk_content_deserializer_get_input_stream (GdkContentDeserializer *deserializer)

 /**
 * gdk_content_deserializer_get_priority:
- * @deserializer: a #GdkContentDeserializer
+ * @deserializer: a `GdkContentDeserializer`
 *
- * Gets the io priority that was passed to gdk_content_deserialize_async().
+ * Gets the I/O priority for the current operation.
 *
- * Returns: the io priority for the current operation
+ * This is the priority that was passed to [funccontent_deserialize_async].
+ *
+ * Returns: the I/O priority for the current operation
 */
 int
 gdk_content_deserializer_get_priority (GdkContentDeserializer *deserializer)
@@ -246,9 +256,11 @@ gdk_content_deserializer_get_priority (GdkContentDeserializer *deserializer)

 /**
 * gdk_content_deserializer_get_cancellable:
- * @deserializer: a #GdkContentDeserializer
+ * @deserializer: a `GdkContentDeserializer`
 *
- * Gets the cancellable that was passed to gdk_content_deserialize_async().
+ * Gets the cancellable for the current operation.
+ *
+ * This is the `GCancellable` that was passed to [func@content_deserialize_async].
 *
 * Returns: (transfer none): the cancellable for the current operation
 */
@@ -262,7 +274,7 @@ gdk_content_deserializer_get_cancellable (GdkContentDeserializer *deserializer)

 /**
 * gdk_content_deserializer_get_user_data:
- * @deserializer: a #GdkContentDeserializer
+ * @deserializer: a `GdkContentDeserializer`
 *
 * Gets the user data that was passed when the deserializer was registered.
 *
@@ -278,7 +290,7 @@ gdk_content_deserializer_get_user_data (GdkContentDeserializer *deserializer)

 /**
 * gdk_content_deserializer_set_task_data:
- * @deserializer: a #GdkContentDeserializer
+ * @deserializer: a `GdkContentDeserializer`
 * @data: data to associate with this operation
 * @notify: destroy notify for @data
 *
@@ -300,9 +312,11 @@ gdk_content_deserializer_set_task_data (GdkContentDeserializer *deserializer,

 /**
 * gdk_content_deserializer_get_task_data:
- * @deserializer: a #GdkContentDeserializer
+ * @deserializer: a `GdkContentDeserializer`
 *
- * Gets the data that was associated with @deserializer via gdk_content_deserializer_set_task_data().
+ * Gets the data that was associated with the current operation.
+ *
+ * See [method@Gdk.ContentDeserializer.set_task_data].
 *
 * Returns: (transfer none): the task data for @deserializer
 */
@@ -329,7 +343,7 @@ gdk_content_deserializer_emit_callback (gpointer data)

 /**
 * gdk_content_deserializer_return_success:
- * @deserializer: a #GdkContentDeserializer
+ * @deserializer: a `GdkContentDeserializer`
 *
 * Indicate that the deserialization has been successfully completed.
 */
@@ -349,10 +363,11 @@ gdk_content_deserializer_return_success (GdkContentDeserializer *deserializer)

 /**
 * gdk_content_deserializer_return_error:
- * @deserializer: a #GdkContentDeserializer
- * @error: a #GError
+ * @deserializer: a `GdkContentDeserializer`
+ * @error: a `GError`
 *
 * Indicate that the deserialization has ended with an error.
+ *
 * This function consumes @error.
 */
 void
@@ -376,8 +391,7 @@ gdk_content_deserializer_return_error (GdkContentDeserializer *deserializer,
 * @data: data that @deserialize can access
 * @notify: destroy notify for @data
 *
- * Registers a function to create objects of a given @type from
- * a serialized representation with the given mime type.
+ * Registers a function to deserialize object of a given type.
 */
 void
 gdk_content_register_deserializer (const char                *mime_type,
@@ -424,18 +438,18 @@ lookup_deserializer (const char *mime_type,
          deserializer->type == type)
        return deserializer;
    }
-  
+
  return NULL;
 }

 /**
 * gdk_content_formats_union_deserialize_gtypes:
- * @formats: (transfer full): a #GdkContentFormats
+ * @formats: (transfer full): a `GdkContentFormats`
 *
 * Add GTypes for mime types in @formats for which deserializers are
 * registered.
 *
- * Return: a new #GdkContentFormats
+ * Return: a new `GdkContentFormats`
 */
 GdkContentFormats *
 gdk_content_formats_union_deserialize_gtypes (GdkContentFormats *formats)
@@ -465,12 +479,12 @@ gdk_content_formats_union_deserialize_gtypes (GdkContentFormats *formats)

 /**
 * gdk_content_formats_union_deserialize_mime_types:
- * @formats: (transfer full): a #GdkContentFormats
+ * @formats: (transfer full): a `GdkContentFormats`
 *
 * Add mime types for GTypes in @formats for which deserializers are
 * registered.
 *
- * Return: a new #GdkContentFormats
+ * Return: a new `GdkContentFormats`
 */
 GdkContentFormats *
 gdk_content_formats_union_deserialize_mime_types (GdkContentFormats *formats)
@@ -511,17 +525,21 @@ deserialize_not_found (GdkContentDeserializer *deserializer)

 /**
 * gdk_content_deserialize_async:
- * @stream: a #GInputStream to read the serialized content from
+ * @stream: a `GInputStream` to read the serialized content from
 * @mime_type: the mime type to deserialize from
 * @type: the GType to deserialize from
- * @io_priority: the io priority of the operation
- * @cancellable: (nullable): optional #GCancellable object
+ * @io_priority: the I/O priority of the operation
+ * @cancellable: (nullable): optional `GCancellable` object
 * @callback: (scope async): callback to call when the operation is done
 * @user_data: (closure): data to pass to the callback function
 *
 * Read content from the given input stream and deserialize it, asynchronously.
- * When the operation is finished, @callback will be called. You can then
- * call gdk_content_deserialize_finish() to get the result of the operation.
+ *
+ * The default I/O priority is %G_PRIORITY_DEFAULT (i.e. 0), and lower numbers
+ * indicate a higher priority.
+ *
+ * When the operation is finished, @callback will be called. You must then
+ * call [func@content_deserialize_finish] to get the result of the operation.
 */
 void
 gdk_content_deserialize_async (GInputStream        *stream,
@@ -553,14 +571,15 @@ gdk_content_deserialize_async (GInputStream        *stream,

 /**
 * gdk_content_deserialize_finish:
- * @result: the #GAsyncResult
+ * @result: the `GAsyncResult`
 * @value: return location for the result of the operation
 * @error: return location for an error
 *
 * Finishes a content deserialization operation.
 *
- * Returns: %TRUE if the operation was successful. In this case, @value is set.
- *          %FALSE if an error occurred. In this case, @error is set
+ * Returns: %TRUE if the operation was successful. In this case,
+ *   @value is set. %FALSE if an error occurred. In this case,
+ *   @error is set
 */
 gboolean
 gdk_content_deserialize_finish (GAsyncResult  *result,
@@ -32,11 +32,6 @@ G_BEGIN_DECLS
 #define GDK_CONTENT_DESERIALIZER(o)           (G_TYPE_CHECK_INSTANCE_CAST ((o), GDK_TYPE_CONTENT_DESERIALIZER, GdkContentDeserializer))
 #define GDK_IS_CONTENT_DESERIALIZER(o)        (G_TYPE_CHECK_INSTANCE_TYPE ((o), GDK_TYPE_CONTENT_DESERIALIZER))

-/**
- * GdkContentDeserializer:
- *
- * Should not be accessed directly.
- */
 typedef struct _GdkContentDeserializer GdkContentDeserializer;

 /**
@@ -44,6 +39,7 @@ typedef struct _GdkContentDeserializer GdkContentDeserializer;
 * @deserializer: a #GdkContentDeserializer
 *
 * The type of a function that can be registered with gdk_content_register_deserializer().
+ *
 * When the function gets called to operate on content, it can call functions on the
 * @deserializer object to obtain the mime type, input stream, user data, etc. for its
 * operation.
@@ -16,46 +16,40 @@
 */

 /**
- * SECTION:gdkcontentformats
- * @Title: Content Formats
- * @Short_description: Advertising and negotiating of content
- *     exchange formats
- * @See_also: #GdkDrag, #GdkDrop, #GdkClipboard, #GdkContentProvider
+ * GdkContentFormats:
 *
- * This section describes the #GdkContentFormats structure that is used to
- * advertise and negotiate the format of content passed between different
- * widgets, windows or applications using for example the clipboard or
- * drag'n'drop.
+ * The `GdkContentFormats` structure is used to advertise and negotiate the
+ * format of content.
 *
- * GDK supports content in 2 forms: #GType and mime type.
- * Using #GTypes is meant only for in-process content transfers. Mime types
+ * You will encounter `GdkContentFormats` when interacting with objects
+ * controlling operations that pass data between different widgets, window
+ * or application, like [class@Gdk.Drag], [class@Gdk.Drop],
+ * [class@Gdk.Clipboard] or [class@Gdk.ContentProvider].
+ *
+ * GDK supports content in 2 forms: `GType` and mime type.
+ * Using `GTypes` is meant only for in-process content transfers. Mime types
 * are meant to be used for data passing both in-process and out-of-process.
 * The details of how data is passed is described in the documentation of
- * the actual implementations.
+ * the actual implementations. To transform between the two forms,
+ * [class@Gdk.ContentSerializer] and [class@Gdk.ContentDeserializer] are used.
 *
- * A #GdkContentFormats describes a set of possible formats content can be
- * exchanged in. It is assumed that this set is ordered. #GTypes are more
- * important than mime types. Order between different #GTypes or mime types
+ * A `GdkContentFormats` describes a set of possible formats content can be
+ * exchanged in. It is assumed that this set is ordered. `GTypes` are more
+ * important than mime types. Order between different `GTypes` or mime types
 * is the order they were added in, most important first. Functions that
- * care about order, such as gdk_content_formats_union() will describe in
- * their documentation how they interpret that order, though in general the
+ * care about order, such as [method@Gdk.ContentFormats.union], will describe
+ * in their documentation how they interpret that order, though in general the
 * order of the first argument is considered the primary order of the result,
 * followed by the order of further arguments.
 *
- * For debugging purposes, the function gdk_content_formats_to_string() exists.
- * It will print a comma-seperated formats of formats from most important to least
- * important.
+ * For debugging purposes, the function [method@Gdk.ContentFormats.to_string]
+ * exists. It will print a comma-separated list of formats from most important
+ * to least important.
 *
- * #GdkContentFormats is an immutable struct. After creation, you cannot change
- * the types it represents. Instead, new #GdkContentFormats have to be created.
- * The #GdkContentFormatsBuilder structure is meant to help in this endeavor.
- */
-
-/**
- * GdkContentFormats:
- *
- * A #GdkContentFormats struct is a reference counted struct
- * and should be treated as opaque.
+ * `GdkContentFormats` is an immutable struct. After creation, you cannot change
+ * the types it represents. Instead, new `GdkContentFormats` have to be created.
+ * The [struct@Gdk.ContentFormatsBuilder]` structure is meant to help in this
+ * endeavor.
 */

 #include "config.h"
@@ -92,7 +86,7 @@ G_DEFINE_BOXED_TYPE (GdkContentFormats, gdk_content_formats,
 *
 * Returns: An interned string for the canonicalized mime type
 *     or %NULL if the string wasn't a valid mime type
- **/
+ */
 const char *
 gdk_intern_mime_type (const char *string)
 {
@@ -134,15 +128,15 @@ gdk_content_formats_new_take (GType *      gtypes,
 * @mime_types: (array length=n_mime_types) (allow-none): Pointer to an
 *   array of mime types
 * @n_mime_types: number of entries in @mime_types.
- * 
- * Creates a new #GdkContentFormats from an array of mime types.
+ *
+ * Creates a new `GdkContentFormats` from an array of mime types.
 *
 * The mime types must be valid and different from each other or the
 * behavior of the return value is undefined. If you cannot guarantee
- * this, use #GdkContentFormatsBuilder instead.
- * 
- * Returns: (transfer full): the new #GdkContentFormats.
- **/
+ * this, use `GdkContentFormatsBuilder` instead.
+ *
+ * Returns: (transfer full): the new `GdkContentFormats`.
+ */
 GdkContentFormats *
 gdk_content_formats_new (const char **mime_types,
                         guint        n_mime_types)
@@ -165,12 +159,12 @@ gdk_content_formats_new (const char **mime_types,

 /**
 * gdk_content_formats_new_for_gtype:
- * @type: a $GType
+ * @type: a `GType`
 *
- * Creates a new #GdkContentFormats for a given #GType.
+ * Creates a new `GdkContentFormats` for a given `GType`.
 *
- * Returns: a new #GdkContentFormats
- **/
+ * Returns: a new `GdkContentFormats`
+ */
 GdkContentFormats *
 gdk_content_formats_new_for_gtype (GType type)
 {
@@ -187,12 +181,12 @@ gdk_content_formats_new_for_gtype (GType type)

 /**
 * gdk_content_formats_ref:
- * @formats:  a #GdkContentFormats
- * 
- * Increases the reference count of a #GdkContentFormats by one.
+ * @formats:  a `GdkContentFormats`
 *
- * Returns: the passed in #GdkContentFormats.
- **/
+ * Increases the reference count of a `GdkContentFormats` by one.
+ *
+ * Returns: the passed in `GdkContentFormats`.
+ */
 GdkContentFormats *
 gdk_content_formats_ref (GdkContentFormats *formats)
 {
@@ -205,12 +199,13 @@ gdk_content_formats_ref (GdkContentFormats *formats)

 /**
 * gdk_content_formats_unref:
- * @formats: a #GdkContentFormats
- * 
- * Decreases the reference count of a #GdkContentFormats by one.
+ * @formats: a `GdkContentFormats`
+ *
+ * Decreases the reference count of a `GdkContentFormats` by one.
+ *
 * If the resulting reference count is zero, frees the formats.
- **/
-void               
+ */
+void
 gdk_content_formats_unref (GdkContentFormats *formats)
 {
  g_return_if_fail (formats != NULL);
@@ -227,15 +222,16 @@ gdk_content_formats_unref (GdkContentFormats *formats)

 /**
 * gdk_content_formats_print:
- * @formats: a #GdkContentFormats
- * @string: a #GString to print into
+ * @formats: a `GdkContentFormats`
+ * @string: a `GString` to print into
 *
 * Prints the given @formats into a string for human consumption.
+ *
 * This is meant for debugging and logging.
 *
 * The form of the representation may change at any time and is
 * not guaranteed to stay identical.
- **/
+ */
 void
 gdk_content_formats_print (GdkContentFormats *formats,
                           GString           *string)
@@ -263,14 +259,15 @@ gdk_content_formats_print (GdkContentFormats *formats,

 /**
 * gdk_content_formats_to_string:
- * @formats: a #GdkContentFormats
+ * @formats: a `GdkContentFormats`
 *
 * Prints the given @formats into a human-readable string.
- * This is a small wrapper around gdk_content_formats_print() to help
- * when debugging.
+ *
+ * This is a small wrapper around [method@Gdk.ContentFormats.print]
+ * to help when debugging.
 *
 * Returns: (transfer full): a new string
- **/
+ */
 char *
 gdk_content_formats_to_string (GdkContentFormats *formats)
 {
@@ -286,13 +283,13 @@ gdk_content_formats_to_string (GdkContentFormats *formats)

 /**
 * gdk_content_formats_union:
- * @first: (transfer full): the #GdkContentFormats to merge into
- * @second: (transfer none): the #GdkContentFormats to merge from
+ * @first: (transfer full): the `GdkContentFormats` to merge into
+ * @second: (transfer none): the `GdkContentFormats` to merge from
 *
 * Append all missing types from @second to @first, in the order
 * they had in @second.
 *
- * Returns: a new #GdkContentFormats
+ * Returns: a new `GdkContentFormats`
 */
 GdkContentFormats *
 gdk_content_formats_union (GdkContentFormats       *first,
@@ -329,8 +326,8 @@ gdk_content_formats_contain_interned_mime_type (const GdkContentFormats *formats

 /**
 * gdk_content_formats_match:
- * @first: the primary #GdkContentFormats to intersect
- * @second: the #GdkContentFormats to intersect with
+ * @first: the primary `GdkContentFormats` to intersect
+ * @second: the `GdkContentFormats` to intersect with
 *
 * Checks if @first and @second have any matching formats.
 *
@@ -349,15 +346,16 @@ gdk_content_formats_match (const GdkContentFormats *first,

 /**
 * gdk_content_formats_match_gtype:
- * @first: the primary #GdkContentFormats to intersect
- * @second: the #GdkContentFormats to intersect with
+ * @first: the primary `GdkContentFormats` to intersect
+ * @second: the `GdkContentFormats` to intersect with
 *
- * Finds the first #GType from @first that is also contained
- * in @second. If no matching #GType is found, %G_TYPE_INVALID
- * is returned.
+ * Finds the first `GType` from @first that is also contained
+ * in @second.
 *
- * Returns: The first common #GType or %G_TYPE_INVALID if none.
- **/
+ * If no matching `GType` is found, %G_TYPE_INVALID is returned.
+ *
+ * Returns: The first common `GType` or %G_TYPE_INVALID if none.
+ */
 GType
 gdk_content_formats_match_gtype (const GdkContentFormats *first,
                                 const GdkContentFormats *second)
@@ -378,15 +376,16 @@ gdk_content_formats_match_gtype (const GdkContentFormats *first,

 /**
 * gdk_content_formats_match_mime_type:
- * @first: the primary #GdkContentFormats to intersect
- * @second: the #GdkContentFormats to intersect with
+ * @first: the primary `GdkContentFormats` to intersect
+ * @second: the `GdkContentFormats` to intersect with
 *
 * Finds the first mime type from @first that is also contained
- * in @second. If no matching mime type is found, %NULL is
- * returned.
+ * in @second.
+ *
+ * If no matching mime type is found, %NULL is returned.
 *
 * Returns: (nullable): The first common mime type or %NULL if none.
- **/
+ */
 const char *
 gdk_content_formats_match_mime_type (const GdkContentFormats *first,
                                     const GdkContentFormats *second)
@@ -407,13 +406,13 @@ gdk_content_formats_match_mime_type (const GdkContentFormats *first,

 /**
 * gdk_content_formats_contain_gtype:
- * @formats: a #GdkContentFormats
- * @type: the #GType to search for
+ * @formats: a `GdkContentFormats`
+ * @type: the `GType` to search for
 *
- * Checks if a given #GType is part of the given @formats.
+ * Checks if a given `GType` is part of the given @formats.
 *
 * Returns: %TRUE if the #GType was found
- **/
+ */
 gboolean
 gdk_content_formats_contain_gtype (const GdkContentFormats *formats,
                                   GType                    type)
@@ -433,13 +432,13 @@ gdk_content_formats_contain_gtype (const GdkContentFormats *formats,

 /**
 * gdk_content_formats_contain_mime_type:
- * @formats: a #GdkContentFormats
+ * @formats: a `GdkContentFormats`
 * @mime_type: the mime type to search for
 *
 * Checks if a given mime type is part of the given @formats.
 *
 * Returns: %TRUE if the mime_type was found
- **/
+ */
 gboolean
 gdk_content_formats_contain_mime_type (const GdkContentFormats *formats,
                                       const char              *mime_type)
@@ -453,18 +452,19 @@ gdk_content_formats_contain_mime_type (const GdkContentFormats *formats,

 /**
 * gdk_content_formats_get_gtypes:
- * @formats: a #GdkContentFormats
+ * @formats: a `GdkContentFormats`
 * @n_gtypes: (out) (optional): optional pointer to take the
 *     number of #GTypes contained in the return value
 *
- * Gets the #GTypes included in @formats. Note that @formats may not
- * contain any #GTypes, in particular when they are empty. In that
- * case %NULL will be returned. 
+ * Gets the `GTypes` included in @formats.
+ *
+ * Note that @formats may not contain any #GTypes, in particular when
+ * they are empty. In that case %NULL will be returned.
 *
 * Returns: (transfer none) (nullable) (array length=n_gtypes):
 *      %G_TYPE_INVALID-terminated array of types included in @formats or
 *      %NULL if none.
- **/
+ */
 const GType *
 gdk_content_formats_get_gtypes (const GdkContentFormats *formats,
                                gsize                   *n_gtypes)
@@ -479,18 +479,19 @@ gdk_content_formats_get_gtypes (const GdkContentFormats *formats,

 /**
 * gdk_content_formats_get_mime_types:
- * @formats: a #GdkContentFormats
+ * @formats: a `GdkContentFormats`
 * @n_mime_types: (out) (allow-none): optional pointer to take the
 *     number of mime types contained in the return value
 *
- * Gets the mime types included in @formats. Note that @formats may not
- * contain any mime types, in particular when they are empty. In that
- * case %NULL will be returned. 
+ * Gets the mime types included in @formats.
 *
- * Returns: (transfer none) (nullable): %NULL-terminated array of 
+ * Note that @formats may not contain any mime types, in particular
+ * when they are empty. In that case %NULL will be returned.
+ *
+ * Returns: (transfer none) (nullable): %NULL-terminated array of
 *     interned strings of mime types included in @formats or %NULL
 *     if none.
- **/
+ */
 const char * const *
 gdk_content_formats_get_mime_types (const GdkContentFormats *formats,
                                    gsize                   *n_mime_types)
@@ -506,9 +507,8 @@ gdk_content_formats_get_mime_types (const GdkContentFormats *formats,
 /**
 * GdkContentFormatsBuilder:
 *
- * A #GdkContentFormatsBuilder struct is an opaque struct. It is meant to
- * not be kept around and only be used to create new #GdkContentFormats
- * objects.
+ * A `GdkContentFormatsBuilder` is an auxiliary struct used to create
+ * new `GdkContentFormats`, and should not be kept around.
 */

 struct _GdkContentFormatsBuilder
@@ -532,12 +532,13 @@ G_DEFINE_BOXED_TYPE (GdkContentFormatsBuilder,
 /**
 * gdk_content_formats_builder_new:
 *
- * Create a new #GdkContentFormatsBuilder object. The resulting builder
- * would create an empty #GdkContentFormats. Use addition functions to add
- * types to it.
+ * Create a new `GdkContentFormatsBuilder` object.
 *
- * Returns: a new #GdkContentFormatsBuilder
- **/
+ * The resulting builder would create an empty `GdkContentFormats`.
+ * Use addition functions to add types to it.
+ *
+ * Returns: a new `GdkContentFormatsBuilder`
+ */
 GdkContentFormatsBuilder *
 gdk_content_formats_builder_new (void)
 {
@@ -551,15 +552,15 @@ gdk_content_formats_builder_new (void)

 /**
 * gdk_content_formats_builder_ref:
- * @builder: a #GdkContentFormatsBuilder
+ * @builder: a `GdkContentFormatsBuilder`
 *
 * Acquires a reference on the given @builder.
 *
- * This function is intended primarily for bindings. #GdkContentFormatsBuilder objects
- * should not be kept around.
+ * This function is intended primarily for bindings.
+ * `GdkContentFormatsBuilder` objects should not be kept around.
 *
- * Returns: (transfer none): the given #GdkContentFormatsBuilder with
- *   its reference count increased
+ * Returns: (transfer none): the given `GdkContentFormatsBuilder`
+ *   with its reference count increased
 */
 GdkContentFormatsBuilder *
 gdk_content_formats_builder_ref (GdkContentFormatsBuilder *builder)
@@ -581,7 +582,7 @@ gdk_content_formats_builder_clear (GdkContentFormatsBuilder *builder)

 /**
 * gdk_content_formats_builder_unref:
- * @builder: a #GdkContentFormatsBuilder
+ * @builder: a `GdkContentFormatsBuilder`
 *
 * Releases a reference on the given @builder.
 */
@@ -602,12 +603,12 @@ gdk_content_formats_builder_unref (GdkContentFormatsBuilder *builder)

 /**
 * gdk_content_formats_builder_free_to_formats: (skip)
- * @builder: a #GdkContentFormatsBuilder
+ * @builder: a `GdkContentFormatsBuilder`
 *
- * Creates a new #GdkContentFormats from the current state of the
+ * Creates a new `GdkContentFormats` from the current state of the
 * given @builder, and frees the @builder instance.
 *
- * Returns: (transfer full): the newly created #GdkContentFormats
+ * Returns: (transfer full): the newly created `GdkContentFormats`
 *   with all the formats added to @builder
 */
 GdkContentFormats *
@@ -626,17 +627,17 @@ gdk_content_formats_builder_free_to_formats (GdkContentFormatsBuilder *builder)

 /**
 * gdk_content_formats_builder_to_formats:
- * @builder: a #GdkContentFormatsBuilder
+ * @builder: a `GdkContentFormats`Builder
 *
- * Creates a new #GdkContentFormats from the given @builder.
+ * Creates a new `GdkContentFormats` from the given @builder.
 *
- * The given #GdkContentFormatsBuilder is reset once this function returns;
+ * The given `GdkContentFormatsBuilder` is reset once this function returns;
 * you cannot call this function multiple times on the same @builder instance.
 *
 * This function is intended primarily for bindings. C code should use
- * gdk_content_formats_builder_free_to_formats().
+ * [method@Gdk.ContentFormatsBuilder.free_to_formats].
 *
- * Returns: (transfer full): the newly created #GdkContentFormats
+ * Returns: (transfer full): the newly created `GdkContentFormats`
 *   with all the formats added to @builder
 */
 GdkContentFormats *
@@ -674,12 +675,12 @@ gdk_content_formats_builder_to_formats (GdkContentFormatsBuilder *builder)

 /**
 * gdk_content_formats_builder_add_formats:
- * @builder: a #GdkContentFormatsBuilder
+ * @builder: a `GdkContentFormatsBuilder`
 * @formats: the formats to add
 *
 * Appends all formats from @formats to @builder, skipping those that
 * already exist.
- **/
+ */
 void
 gdk_content_formats_builder_add_formats (GdkContentFormatsBuilder *builder,
                                         const GdkContentFormats  *formats)
@@ -698,10 +699,10 @@ gdk_content_formats_builder_add_formats (GdkContentFormatsBuilder *builder,

 /**
 * gdk_content_formats_builder_add_gtype:
- * @builder: a #GdkContentFormatsBuilder
- * @type: a #GType
+ * @builder: a `GdkContentFormats`Builder
+ * @type: a `GType`
 *
- * Appends @gtype to @builder if it has not already been added.
+ * Appends @type to @builder if it has not already been added.
 **/
 void
 gdk_content_formats_builder_add_gtype (GdkContentFormatsBuilder *builder,
@@ -719,11 +720,11 @@ gdk_content_formats_builder_add_gtype (GdkContentFormatsBuilder *builder,

 /**
 * gdk_content_formats_builder_add_mime_type:
- * @builder: a #GdkContentFormatsBuilder
+ * @builder: a `GdkContentFormatsBuilder`
 * @mime_type: a mime type
 *
 * Appends @mime_type to @builder if it has not already been added.
- **/
+ */
 void
 gdk_content_formats_builder_add_mime_type (GdkContentFormatsBuilder *builder,
                                           const char               *mime_type)
@@ -25,20 +25,17 @@
 #include "gdkintl.h"

 /**
- * SECTION:gdkcontentprovider
- * @Short_description: Provides content for data transfer between applications
- * @Title: GdkContentProvider
- * @See_also: #GdkContentSerializer, #GdkContentDeserializer
+ * GdkContentProvider:
 *
- * A GdkContentProvider is used to provide content for the clipboard in
- * a number of formats.
+ * A `GdkContentProvider` is used to provide content for the clipboard or
+ * for drag-and-drop operations in a number of formats.
 *
- * To create a GdkContentProvider, use gdk_content_provider_new_for_value() or
- * gdk_content_provider_new_for_bytes().
+ * To create a `GdkContentProvider`, use [ctor@Gdk.ContentProvider.new_for_value]
+ * or [ctor@Gdk.ContentProvider.new_for_bytes].
 *
 * GDK knows how to handle common text and image formats out-of-the-box. See
- * #GdkContentSerializer and #GdkContentDeserializer if you want to add support
- * for application-specific data formats.
+ * [class@Gdk.ContentSerializer] and [class@Gdk.ContentDeserializer] if you want
+ * to add support for application-specific data formats.
 */

 typedef struct _GdkContentProviderPrivate GdkContentProviderPrivate;
@@ -171,7 +168,7 @@ gdk_content_provider_class_init (GdkContentProviderClass *class)
  class->get_value = gdk_content_provider_real_get_value;

  /**
-   * GdkContentProvider:formats:
+   * GdkContentProvider:formats: (attributes org.gtk.Property.get=gdk_content_provider_ref_formats)
   *
   * The possible formats that the provider can provide its data in.
   */
@@ -185,7 +182,7 @@ gdk_content_provider_class_init (GdkContentProviderClass *class)
                        G_PARAM_EXPLICIT_NOTIFY);

  /**
-   * GdkContentProvider:storable-formats:
+   * GdkContentProvider:storable-formats: (attributes org.gtk.Property.get=gdk_content_provider_ref_storable_formats)
   *
   * The subset of formats that clipboard managers should store this provider's data in.
   */
@@ -220,13 +217,13 @@ gdk_content_provider_init (GdkContentProvider *provider)
 }

 /**
- * gdk_content_provider_ref_formats:
+ * gdk_content_provider_ref_formats: (attributes org.gtk.Method.get_property=formats)
 * @provider: a #GdkContentProvider
 *
 * Gets the formats that the provider can provide its current contents in.
 *
 * Returns: (transfer full): The formats of the provider
- **/
+ */
 GdkContentFormats *
 gdk_content_provider_ref_formats (GdkContentProvider *provider)
 {
@@ -236,17 +233,18 @@ gdk_content_provider_ref_formats (GdkContentProvider *provider)
 }

 /**
- * gdk_content_provider_ref_storable_formats:
+ * gdk_content_provider_ref_storable_formats: (attributes org.gtk.Method.get_property=storable-formats)
 * @provider: a #GdkContentProvider
 *
 * Gets the formats that the provider suggests other applications to store
- * the data in.  
+ * the data in.
+ *
 * An example of such an application would be a clipboard manager.
 *
- * This can be assumed to be a subset of gdk_content_provider_ref_formats().
+ * This can be assumed to be a subset of [method@Gdk.ContentProvider.ref_formats].
 *
 * Returns: (transfer full): The storable formats of the provider
- **/
+ */
 GdkContentFormats *
 gdk_content_provider_ref_storable_formats (GdkContentProvider *provider)
 {
@@ -257,9 +255,9 @@ gdk_content_provider_ref_storable_formats (GdkContentProvider *provider)

 /**
 * gdk_content_provider_content_changed:
- * @provider: a #GdkContentProvider
+ * @provider: a `GdkContentProvider`
 *
- * Emits the #GdkContentProvider::content-changed signal.
+ * Emits the ::content-changed signal.
 */
 void
 gdk_content_provider_content_changed (GdkContentProvider *provider)
@@ -273,26 +271,27 @@ gdk_content_provider_content_changed (GdkContentProvider *provider)

 /**
 * gdk_content_provider_write_mime_type_async:
- * @provider: a #GdkContentProvider
+ * @provider: a `GdkContentProvider`
 * @mime_type: the mime type to provide the data in
- * @stream: the #GOutputStream to write to
- * @io_priority: the [I/O priority][io-priority]
- * of the request. 
- * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
+ * @stream: the `GOutputStream` to write to
+ * @io_priority: I/O priority of the request.
+ * @cancellable: (nullable): optional `GCancellable` object, %NULL to ignore.
 * @callback: (scope async): callback to call when the request is satisfied
 * @user_data: (closure): the data to pass to callback function
 *
 * Asynchronously writes the contents of @provider to @stream in the given
- * @mime_type. When the operation is finished @callback will be called. You
- * can then call gdk_content_provider_write_mime_type_finish() to get the 
- * result of the operation.
+ * @mime_type.
+ *
+ * When the operation is finished @callback will be called. You must then call
+ * [method@Gdk.ContentProvider.write_mime_type_finish] to get the result
+ * of the operation.
 *
 * The given mime type does not need to be listed in the formats returned by
- * gdk_content_provider_ref_formats(). However, if the given #GType is not
- * supported, #G_IO_ERROR_NOT_SUPPORTED will be reported.
+ * [method@Gdk.ContentProvider.ref_formats]. However, if the given `GType` is
+ * not supported, #G_IO_ERROR_NOT_SUPPORTED will be reported.
 *
 * The given @stream will not be closed.
- **/
+ */
 void
 gdk_content_provider_write_mime_type_async (GdkContentProvider  *provider,
                                            const char          *mime_type,
@@ -318,17 +317,17 @@ gdk_content_provider_write_mime_type_async (GdkContentProvider  *provider,

 /**
 * gdk_content_provider_write_mime_type_finish:
- * @provider: a #GdkContentProvider
- * @result: a #GAsyncResult
- * @error: a #GError location to store the error occurring, or %NULL to 
- *     ignore.
+ * @provider: a `GdkContentProvider`
+ * @result: a `GAsyncResult`
+ * @error: a `GError` location to store the error occurring, or %NULL to ignore
 *
- * Finishes an asynchronous write operation started with
- * gdk_content_provider_write_mime_type_async().
+ * Finishes an asynchronous write operation.
+ *
+ * See [method@Gdk.ContentProvider.write_mime_type_async].
 *
 * Returns: %TRUE if the operation was completed successfully. Otherwise
 *     @error will be set to describe the failure.
- **/
+ */
 gboolean
 gdk_content_provider_write_mime_type_finish (GdkContentProvider  *provider,
                                             GAsyncResult        *result,
@@ -342,22 +341,21 @@ gdk_content_provider_write_mime_type_finish (GdkContentProvider  *provider,

 /**
 * gdk_content_provider_get_value:
- * @provider: a #GdkContentProvider
- * @value: the #GValue to fill
- * @error: a #GError location to store the error occurring, or %NULL to 
- *     ignore.
+ * @provider: a `GdkContentProvider`
+ * @value: the `GValue` to fill
+ * @error: a `GError` location to store the error occurring, or %NULL to ignore
 *
 * Gets the contents of @provider stored in @value.
 *
- * The @value will have been initialized to the #GType the value should be
- * provided in. This given #GType does not need to be listed in the formats
- * returned by gdk_content_provider_ref_formats(). However, if the given
- * #GType is not supported, this operation can fail and
+ * The @value will have been initialized to the `GType` the value should be
+ * provided in. This given `GType` does not need to be listed in the formats
+ * returned by [method@Gdk.ContentProvider.ref_formats]. However, if the
+ * given `GType` is not supported, this operation can fail and
 * #G_IO_ERROR_NOT_SUPPORTED will be reported.
 *
 * Returns: %TRUE if the value was set successfully. Otherwise
 *     @error will be set to describe the failure.
- **/
+ */
 gboolean
 gdk_content_provider_get_value (GdkContentProvider  *provider,
                                GValue              *value,
@@ -38,12 +38,6 @@ G_BEGIN_DECLS

 typedef struct _GdkContentProviderClass GdkContentProviderClass;

-/**
- * GdkContentProvider:
- *
- * Should not be directly accessed.
- */
-
 struct _GdkContentProvider
 {
  GObject parent;
@@ -108,12 +108,12 @@ gdk_content_provider_value_init (GdkContentProviderValue *content)

 /**
 * gdk_content_provider_new_for_value:
- * @value: a #GValue
+ * @value: a `GValue`
 *
 * Create a content provider that provides the given @value.
 *
- * Returns: a new #GdkContentProvider
- **/
+ * Returns: a new `GdkContentProvider`
+ */
 GdkContentProvider *
 gdk_content_provider_new_for_value (const GValue *value)
 {
@@ -139,8 +139,8 @@ gdk_content_provider_new_for_value (const GValue *value)
 * The value is provided using G_VALUE_COLLECT(), so the same rules
 * apply as when calling g_object_new() or g_object_set().
 *
- * Returns: a new #GdkContentProvider
- **/
+ * Returns: a new `GdkContentProvider`
+ */
 GdkContentProvider *
 gdk_content_provider_new_typed (GType type,
                                ...)
@@ -406,16 +406,15 @@ gdk_content_provider_union_init (GdkContentProviderUnion *self)
 * This allows an easy way to support providing data in different formats.
 * For example, an image may be provided by its file and by the image
 * contents with a call such as
- * |[<!-- language="C" -->
+ * ```c
 * gdk_content_provider_new_union ((GdkContentProvider *[2]) {
 *                                   gdk_content_provider_new_typed (G_TYPE_FILE, file),
 *                                   gdk_content_provider_new_typed (G_TYPE_TEXTURE, texture)
 *                                 }, 2);
- * ]|
+ * ```
 *
- *
- * Returns: a new #GdkContentProvider
- **/
+ * Returns: a new `GdkContentProvider`
+ */
 GdkContentProvider *
 gdk_content_provider_new_union (GdkContentProvider **providers,
                                gsize                n_providers)
@@ -576,13 +575,13 @@ gdk_content_provider_bytes_init (GdkContentProviderBytes *content)
 /**
 * gdk_content_provider_new_for_bytes:
 * @mime_type: the mime type
- * @bytes: (transfer none): a #GBytes with the data for @mime_type
+ * @bytes: (transfer none): a `GBytes` with the data for @mime_type
 *
 * Create a content provider that provides the given @bytes as data for
 * the given @mime_type.
 *
- * Returns: a new #GdkContentProvider
- **/
+ * Returns: a new `GdkContentProvider`
+ */
 GdkContentProvider *
 gdk_content_provider_new_for_bytes (const char *mime_type,
                                    GBytes     *bytes)
@@ -32,13 +32,20 @@


 /**
- * SECTION:gdkcontentserializer
- * @Short_description: Serialize content for transfer
- * @Title: GdkContentSerializer
- * @See_also: #GdkContentDeserializer, #GdkContentProvider
+ * GdkContentSerializer:
 *
- * A GdkContentSerializer is used to serialize content for inter-application
- * data transfers.
+ * A `GdkContentSerializer` is used to serialize content for
+ * inter-application data transfers.
+ *
+ * The `GdkContentSerializer` transforms an object that is identified
+ * by a GType into a serialized form (i.e. a byte stream) that is
+ * identified by a mime type.
+ *
+ * GTK provides serializers and deserializers for common data types
+ * such as text, colors, images or file lists. To register your own
+ * serialization functions, use [func@content_register_serializer].
+ *
+ * Also see [class@Gdk.ContentDeserializer].
 */

 typedef struct _Serializer Serializer;
@@ -169,7 +176,7 @@ gdk_content_serializer_run (const char              *mime_type,

 /**
 * gdk_content_serializer_get_mime_type:
- * @serializer: a #GdkContentSerializer
+ * @serializer: a `GdkContentSerializer`
 *
 * Gets the mime type to serialize to.
 *
@@ -185,11 +192,11 @@ gdk_content_serializer_get_mime_type (GdkContentSerializer *serializer)

 /**
 * gdk_content_serializer_get_gtype:
- * @serializer: a #GdkContentSerializer
+ * @serializer: a `GdkContentSerializer`
 *
- * Gets the GType to of the object to serialize.
+ * Gets the `GType` to of the object to serialize.
 *
- * Returns: the GType for the current operation
+ * Returns: the `GType` for the current operation
 */
 GType
 gdk_content_serializer_get_gtype (GdkContentSerializer *serializer)
@@ -201,11 +208,11 @@ gdk_content_serializer_get_gtype (GdkContentSerializer *serializer)

 /**
 * gdk_content_serializer_get_value:
- * @serializer: a #GdkContentSerializer
+ * @serializer: a `GdkContentSerializer`
 *
- * Gets the #GValue to read the object to serialize from.
+ * Gets the `GValue` to read the object to serialize from.
 *
- * Returns: (transfer none): the #GValue for the current operation
+ * Returns: (transfer none): the `GValue` for the current operation
 */
 const GValue *
 gdk_content_serializer_get_value (GdkContentSerializer *serializer)
@@ -217,9 +224,11 @@ gdk_content_serializer_get_value (GdkContentSerializer *serializer)

 /**
 * gdk_content_serializer_get_output_stream:
- * @serializer: a #GdkContentSerializer
+ * @serializer: a `GdkContentSerializer`
 *
- * Gets the output stream that was passed to gdk_content_serialize_async().
+ * Gets the output stream for the current operation.
+ *
+ * This is the stream that was passed to [func@content_serialize_async].
 *
 * Returns: (transfer none): the output stream for the current operation
 */
@@ -233,11 +242,13 @@ gdk_content_serializer_get_output_stream (GdkContentSerializer *serializer)

 /**
 * gdk_content_serializer_get_priority:
- * @serializer: a #GdkContentSerializer
+ * @serializer: a `GdkContentSerializer`
 *
- * Gets the io priority that was passed to gdk_content_serialize_async().
+ * Gets the I/O priority for the current operation.
 *
- * Returns: the io priority for the current operation
+ * This is the priority that was passed to [func@content_serialize_async].
+ *
+ * Returns: the I/O priority for the current operation
 */
 int
 gdk_content_serializer_get_priority (GdkContentSerializer *serializer)
@@ -249,9 +260,11 @@ gdk_content_serializer_get_priority (GdkContentSerializer *serializer)

 /**
 * gdk_content_serializer_get_cancellable:
- * @serializer: a #GdkContentSerializer
+ * @serializer: a `GdkContentSerializer`
 *
- * Gets the cancellable that was passed to gdk_content_serialize_async().
+ * Gets the cancellable for the current operation.
+ *
+ * This is the `GCancellable` that was passed to [content_serialize_async].
 *
 * Returns: (transfer none): the cancellable for the current operation
 */
@@ -265,7 +278,7 @@ gdk_content_serializer_get_cancellable (GdkContentSerializer *serializer)

 /**
 * gdk_content_serializer_get_user_data:
- * @serializer: a #GdkContentSerializer
+ * @serializer: a `GdkContentSerializer`
 *
 * Gets the user data that was passed when the serializer was registered.
 *
@@ -281,7 +294,7 @@ gdk_content_serializer_get_user_data (GdkContentSerializer *serializer)

 /**
 * gdk_content_serializer_set_task_data:
- * @serializer: a #GdkContentSerializer
+ * @serializer: a `GdkContentSerializer`
 * @data: data to associate with this operation
 * @notify: destroy notify for @data
 *
@@ -303,9 +316,11 @@ gdk_content_serializer_set_task_data (GdkContentSerializer   *serializer,

 /**
 * gdk_content_serializer_get_task_data:
- * @serializer: a #GdkContentSerializer
+ * @serializer: a `GdkContentSerializer`
 *
- * Gets the data that was associated with @serializer via gdk_content_serializer_set_task_data().
+ * Gets the data that was associated with the current operation.
+ *
+ * See [method@Gdk.ContentSerializer.set_task_data].
 *
 * Returns: (transfer none): the task data for @serializer
 */
@@ -332,7 +347,7 @@ gdk_content_serializer_emit_callback (gpointer data)

 /**
 * gdk_content_serializer_return_success:
- * @serializer: a #GdkContentSerializer
+ * @serializer: a `GdkContentSerializer`
 *
 * Indicate that the serialization has been successfully completed.
 */
@@ -352,10 +367,11 @@ gdk_content_serializer_return_success (GdkContentSerializer *serializer)

 /**
 * gdk_content_serializer_return_error:
- * @serializer: a #GdkContentSerializer
- * @error: a #GError
+ * @serializer: a `GdkContentSerializer`
+ * @error: a `GError`
 *
 * Indicate that the serialization has ended with an error.
+ *
 * This function consumes @error.
 */
 void
@@ -379,8 +395,7 @@ gdk_content_serializer_return_error (GdkContentSerializer *serializer,
 * @data: data that @serialize can access
 * @notify: destroy notify for @data
 *
- * Registers a function to convert objects of the given @type to
- * a serialized representation with the given mime type.
+ * Registers a function to serialize objects of a given type.
 */
 void
 gdk_content_register_serializer (GType                    type,
@@ -433,12 +448,12 @@ lookup_serializer (const char *mime_type,

 /**
 * gdk_content_formats_union_serialize_gtypes:
- * @formats: (transfer full): a #GdkContentFormats
+ * @formats: (transfer full): a `GdkContentFormats`
 *
 * Add GTypes for the mime types in @formats for which serializers are
 * registered.
 *
- * Return: a new #GdkContentFormats
+ * Return: a new `GdkContentFormats`
 */
 GdkContentFormats *
 gdk_content_formats_union_serialize_gtypes (GdkContentFormats *formats)
@@ -468,12 +483,12 @@ gdk_content_formats_union_serialize_gtypes (GdkContentFormats *formats)

 /**
 * gdk_content_formats_union_serialize_mime_types:
- * @formats: (transfer full):  a #GdkContentFormats
+ * @formats: (transfer full):  a `GdkContentFormats`
 *
 * Add mime types for GTypes in @formats for which serializers are
 * registered.
 *
- * Return: a new #GdkContentFormats
+ * Return: a new `GdkContentFormats`
 */
 GdkContentFormats *
 gdk_content_formats_union_serialize_mime_types (GdkContentFormats *formats)
@@ -514,17 +529,21 @@ serialize_not_found (GdkContentSerializer *serializer)

 /**
 * gdk_content_serialize_async:
- * @stream: a #GOutputStream to write the serialized content to
+ * @stream: a `GOutputStream` to write the serialized content to
 * @mime_type: the mime type to serialize to
 * @value: the content to serialize
- * @io_priority: the io priority of the operation
+ * @io_priority: the I/O priority of the operation
 * @cancellable: (nullable): optional #GCancellable object
 * @callback: (scope async): callback to call when the operation is done
 * @user_data: (closure): data to pass to the callback function
 *
 * Serialize content and write it to the given output stream, asynchronously.
- * When the operation is finished, @callback will be called. You can then
- * call gdk_content_serialize_finish() to get the result of the operation.
+ *
+ * The default I/O priority is %G_PRIORITY_DEFAULT (i.e. 0), and lower numbers
+ * indicate a higher priority.
+ *
+ * When the operation is finished, @callback will be called. You must then
+ * call [func@content_serialize_finish] to get the result of the operation.
 */
 void
 gdk_content_serialize_async (GOutputStream       *stream,
@@ -556,7 +575,7 @@ gdk_content_serialize_async (GOutputStream       *stream,

 /**
 * gdk_content_serialize_finish:
- * @result: the #GAsyncResult
+ * @result: the `GAsyncResult`
 * @error: return location for an error
 *
 * Finishes a content serialization operation.
@@ -32,11 +32,6 @@ G_BEGIN_DECLS
 #define GDK_CONTENT_SERIALIZER(o)           (G_TYPE_CHECK_INSTANCE_CAST ((o), GDK_TYPE_CONTENT_SERIALIZER, GdkContentSerializer))
 #define GDK_IS_CONTENT_SERIALIZER(o)        (G_TYPE_CHECK_INSTANCE_TYPE ((o), GDK_TYPE_CONTENT_SERIALIZER))

-/**
- * GdkContentSerializer:
- *
- * Should not be accessed directly.
- */
 typedef struct _GdkContentSerializer GdkContentSerializer;

 /**
@@ -44,6 +39,7 @@ typedef struct _GdkContentSerializer GdkContentSerializer;
 * @serializer: a #GdkContentSerializer
 *
 * The type of a function that can be registered with gdk_content_register_serializer().
+ *
 * When the function gets called to operate on content, it can call functions on the
 * @serializer object to obtain the mime type, output stream, user data, etc. for its
 * operation.
@@ -37,50 +37,42 @@
 #include <errno.h>

 /**
- * SECTION:cursors
- * @Short_description: Named and texture cursors
- * @Title: Cursors
+ * GdkCursor:
 *
- * These functions are used to create and destroy cursors. Cursors
- * are immutable objects, so once you created them, there is no way
- * to modify them later. Create a new cursor when you want to change
+ * `GdkCursor` is used to create and destroy cursors.
+ *
+ * Cursors are immutable objects, so once you created them, there is no way
+ * to modify them later. You should create a new cursor when you want to change
 * something about it.
 *
- * Cursors by themselves are not very interesting, they must be
- * bound to a window for users to see them. This is done with
- * gdk_surface_set_cursor() or gdk_surface_set_device_cursor().
- * Applications will typically use higher-level GTK functions such
- * as gtk_widget_set_cursor() instead.
+ * Cursors by themselves are not very interesting: they must be bound to a
+ * window for users to see them. This is done with [method@Gdk.Surface.set_cursor]
+ * or [method@Gdk.Surface.set_device_cursor]. Applications will typically
+ * use higher-level GTK functions such as [method@Gtk.Widget.set_cursor]`
+ * instead.
 *
- * Cursors are not bound to a given #GdkDisplay, so they can be shared.
+ * Cursors are not bound to a given [class@Gdk.Display], so they can be shared.
 * However, the appearance of cursors may vary when used on different
 * platforms.
 *
+ * ## Named and texture cursors
+ *
 * There are multiple ways to create cursors. The platform's own cursors
- * can be created with gdk_cursor_new_from_name(). That function lists
+ * can be created with [ctor@Gdk.Cursor.new_from_name]. That function lists
 * the commonly available names that are shared with the CSS specification.
 * Other names may be available, depending on the platform in use. On some
 * platforms, what images are used for named cursors may be influenced by
 * the cursor theme.
 *
- * Another option to create a cursor is to use gdk_cursor_new_from_texture()
+ * Another option to create a cursor is to use [ctor@Gdk.Cursor.new_from_texture]
 * and provide an image to use for the cursor.
 *
 * To ease work with unsupported cursors, a fallback cursor can be provided.
- * If a #GdkSurface cannot use a cursor because of the reasons mentioned above,
- * it will try the fallback cursor. Fallback cursors can themselves have fallback
- * cursors again, so it is possible to provide a chain of progressively easier
- * to support cursors. If none of the provided cursors can be supported, the
- * default cursor will be the ultimate fallback.
- */
-
-/**
- * GdkCursor:
- *
- * A #GdkCursor represents a cursor. Its contents are private.
- *
- * Cursors are immutable objects, so they can not change after
- * they have been constructed.
+ * If a [class@Gdk.Surface] cannot use a cursor because of the reasons mentioned
+ * above, it will try the fallback cursor. Fallback cursors can themselves have
+ * fallback cursors again, so it is possible to provide a chain of progressively
+ * easier to support cursors. If none of the provided cursors can be supported,
+ * the default cursor will be the ultimate fallback.
 */

 enum {
@@ -177,6 +169,11 @@ gdk_cursor_class_init (GdkCursorClass *cursor_class)
  object_class->set_property = gdk_cursor_set_property;
  object_class->finalize = gdk_cursor_finalize;

+  /**
+   * GdkCursor:fallback: (attributes org.gtk.Property.get=gdk_cursor_get_fallback)
+   *
+   * Cursor to fall back to if this cursor cannot be displayed.
+   */
  g_object_class_install_property (object_class,
                                   PROP_FALLBACK,
                                   g_param_spec_object ("fallback",
@@ -185,6 +182,12 @@ gdk_cursor_class_init (GdkCursorClass *cursor_class)
                                                        GDK_TYPE_CURSOR,
                                                        G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY |
                                                        G_PARAM_STATIC_STRINGS));
+
+  /**
+   * GdkCursor:hotspot-x: (attributes org.gtk.Property.get=gdk_cursor_get_hotspot_x)
+   *
+   * X position of the cursor hotspot in the cursor image.
+   */
  g_object_class_install_property (object_class,
                                   PROP_HOTSPOT_X,
                                   g_param_spec_int ("hotspot-x",
@@ -193,6 +196,12 @@ gdk_cursor_class_init (GdkCursorClass *cursor_class)
                                                     0, G_MAXINT, 0,
                                                     G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY |
                                                     G_PARAM_STATIC_STRINGS));
+
+  /**
+   * GdkCursor:hotspot-y: (attributes org.gtk.Property.get=gdk_cursor_get_hotspot_y)
+   *
+   * Y position of the cursor hotspot in the cursor image.
+   */
  g_object_class_install_property (object_class,
                                   PROP_HOTSPOT_Y,
                                   g_param_spec_int ("hotspot-y",
@@ -201,6 +210,14 @@ gdk_cursor_class_init (GdkCursorClass *cursor_class)
                                                     0, G_MAXINT, 0,
                                                     G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY |
                                                     G_PARAM_STATIC_STRINGS));
+
+  /**
+   * GdkCursor:name: (attributes org.gtk.Property.get=gdk_cursor_get_name)
+   *
+   * Name of this this cursor.
+   *
+   * The name will be %NULL if the cursor was created from a texture.
+   */
  g_object_class_install_property (object_class,
                                   PROP_NAME,
                                   g_param_spec_string ("name",
@@ -209,6 +226,14 @@ gdk_cursor_class_init (GdkCursorClass *cursor_class)
                                                        NULL,
                                                        G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY |
                                                        G_PARAM_STATIC_STRINGS));
+
+  /**
+   * GdkCursor:texture:
+   *
+   * The texture displayed by this cursor.
+   *
+   * The texture will be %NULL if the cursor was created from a name.
+   */
  g_object_class_install_property (object_class,
                                   PROP_TEXTURE,
                                   g_param_spec_object ("texture",
@@ -273,7 +298,7 @@ gdk_cursor_equal (gconstpointer a,
 /**
 * gdk_cursor_new_from_name:
 * @name: the name of the cursor
- * @fallback: (allow-none): %NULL or the #GdkCursor to fall back to when
+ * @fallback: (allow-none): %NULL or the `GdkCursor` to fall back to when
 *     this one cannot be supported
 *
 * Creates a new cursor by looking up @name in the current cursor
@@ -281,44 +306,20 @@ gdk_cursor_equal (gconstpointer a,
 *
 * A recommended set of cursor names that will work across different
 * platforms can be found in the CSS specification:
- * - "none"
- * - ![](default_cursor.png) "default"
- * - ![](help_cursor.png) "help"
- * - ![](pointer_cursor.png) "pointer"
- * - ![](context_menu_cursor.png) "context-menu"
- * - ![](progress_cursor.png) "progress"
- * - ![](wait_cursor.png) "wait"
- * - ![](cell_cursor.png) "cell"
- * - ![](crosshair_cursor.png) "crosshair"
- * - ![](text_cursor.png) "text"
- * - ![](vertical_text_cursor.png) "vertical-text"
- * - ![](alias_cursor.png) "alias"
- * - ![](copy_cursor.png) "copy"
- * - ![](no_drop_cursor.png) "no-drop"
- * - ![](move_cursor.png) "move"
- * - ![](not_allowed_cursor.png) "not-allowed"
- * - ![](grab_cursor.png) "grab"
- * - ![](grabbing_cursor.png) "grabbing"
- * - ![](all_scroll_cursor.png) "all-scroll"
- * - ![](col_resize_cursor.png) "col-resize"
- * - ![](row_resize_cursor.png) "row-resize"
- * - ![](n_resize_cursor.png) "n-resize"
- * - ![](e_resize_cursor.png) "e-resize"
- * - ![](s_resize_cursor.png) "s-resize"
- * - ![](w_resize_cursor.png) "w-resize"
- * - ![](ne_resize_cursor.png) "ne-resize"
- * - ![](nw_resize_cursor.png) "nw-resize"
- * - ![](sw_resize_cursor.png) "sw-resize"
- * - ![](se_resize_cursor.png) "se-resize"
- * - ![](ew_resize_cursor.png) "ew-resize"
- * - ![](ns_resize_cursor.png) "ns-resize"
- * - ![](nesw_resize_cursor.png) "nesw-resize"
- * - ![](nwse_resize_cursor.png) "nwse-resize"
- * - ![](zoom_in_cursor.png) "zoom-in"
- * - ![](zoom_out_cursor.png) "zoom-out"
 *
+ * | | | | |
+ * | --- | --- | ---- | --- |
+ * | "none" | ![](default_cursor.png) "default" | ![](help_cursor.png) "help" | ![](pointer_cursor.png) "pointer" |
+ * | ![](context_menu_cursor.png) "context-menu" | ![](progress_cursor.png) "progress" | ![](wait_cursor.png) "wait" | ![](cell_cursor.png) "cell" |
+ * | ![](crosshair_cursor.png) "crosshair" | ![](text_cursor.png) "text" | ![](vertical_text_cursor.png) "vertical-text" | ![](alias_cursor.png) "alias" |
+ * | ![](copy_cursor.png) "copy" | ![](no_drop_cursor.png) "no-drop" | ![](move_cursor.png) "move" | ![](not_allowed_cursor.png) "not-allowed" |
+ * | ![](grab_cursor.png) "grab" | ![](grabbing_cursor.png) "grabbing" | ![](all_scroll_cursor.png) "all-scroll" | ![](col_resize_cursor.png) "col-resize" |
+ * | ![](row_resize_cursor.png) "row-resize" | ![](n_resize_cursor.png) "n-resize" | ![](e_resize_cursor.png) "e-resize" | ![](s_resize_cursor.png) "s-resize" |
+ * | ![](w_resize_cursor.png) "w-resize" | ![](ne_resize_cursor.png) "ne-resize" | ![](nw_resize_cursor.png) "nw-resize" | ![](sw_resize_cursor.png) "sw-resize" |
+ * | ![](se_resize_cursor.png) "se-resize" | ![](ew_resize_cursor.png) "ew-resize" | ![](ns_resize_cursor.png) "ns-resize" | ![](nesw_resize_cursor.png) "nesw-resize" |
+ * | ![](nwse_resize_cursor.png) "nwse-resize" | ![](zoom_in_cursor.png) "zoom-in" | ![](zoom_out_cursor.png) "zoom-out" | |
 *
- * Returns: (nullable): a new #GdkCursor, or %NULL if there is no
+ * Returns: (nullable): a new `GdkCursor`, or %NULL if there is no
 *   cursor with the given name
 */
 GdkCursor *
@@ -339,12 +340,12 @@ gdk_cursor_new_from_name (const char *name,
 * @texture: the texture providing the pixel data
 * @hotspot_x: the horizontal offset of the “hotspot” of the cursor
 * @hotspot_y: the vertical offset of the “hotspot” of the cursor
- * @fallback: (allow-none): %NULL or the #GdkCursor to fall back to when
+ * @fallback: (allow-none): %NULL or the `GdkCursor` to fall back to when
 *     this one cannot be supported
 *
- * Creates a new cursor from a #GdkTexture.
+ * Creates a new cursor from a `GdkTexture`.
 *
- * Returns: a new #GdkCursor.
+ * Returns: a new `GdkCursor`
 */
 GdkCursor *
 gdk_cursor_new_from_texture (GdkTexture *texture,
@@ -366,19 +367,19 @@ gdk_cursor_new_from_texture (GdkTexture *texture,
 }

 /**
- * gdk_cursor_get_fallback:
- * @cursor: a #GdkCursor.
+ * gdk_cursor_get_fallback: (attributes org.gtk.Method.get_property=fallback)
+ * @cursor: a `GdkCursor`
 *
- * Returns the fallback for this @cursor. The fallback will be used if this
- * cursor is not available on a given #GdkDisplay.
+ * Returns the fallback for this @cursor.
 *
- * For named cursors, this can happen when using nonstandard names or when
- * using an incomplete cursor theme.
- * For textured cursors, this can happen when the texture is too large or
- * when the #GdkDisplay it is used on does not support textured cursors.
+ * The fallback will be used if this cursor is not available on a given
+ * `GdkDisplay`. For named cursors, this can happen when using nonstandard
+ * names or when using an incomplete cursor theme. For textured cursors,
+ * this can happen when the texture is too large or when the `GdkDisplay`
+ * it is used on does not support textured cursors.
 *
- * Returns: (transfer none) (nullable): the fallback of the cursor or %NULL to use
- *     the default cursor as fallback.
+ * Returns: (transfer none) (nullable): the fallback of the cursor or %NULL
+ *  to use the default cursor as fallback.
 */
 GdkCursor *
 gdk_cursor_get_fallback (GdkCursor *cursor)
@@ -389,14 +390,15 @@ gdk_cursor_get_fallback (GdkCursor *cursor)
 }

 /**
- * gdk_cursor_get_name:
- * @cursor: a #GdkCursor.
+ * gdk_cursor_get_name: (attributes org.gtk.Method.get_property=name)
+ * @cursor: a `GdkCursor`
 *
- * Returns the name of the cursor. If the cursor is not a named cursor, %NULL
- * will be returned.
+ * Returns the name of the cursor.
 *
- * Returns: (transfer none) (nullable): the name of the cursor or %NULL if it is not
- *     a named cursor
+ * If the cursor is not a named cursor, %NULL will be returned.
+ *
+ * Returns: (transfer none) (nullable): the name of the cursor or %NULL
+ *   if it is not a named cursor
 */
 const char *
 gdk_cursor_get_name (GdkCursor *cursor)
@@ -410,11 +412,12 @@ gdk_cursor_get_name (GdkCursor *cursor)
 * gdk_cursor_get_texture:
 * @cursor: a #GdkCursor.
 *
- * Returns the texture for the cursor. If the cursor is a named cursor, %NULL
- * will be returned.
+ * Returns the texture for the cursor.
 *
- * Returns: (transfer none) (nullable): the texture for cursor or %NULL if it is a
- *     named cursor
+ * If the cursor is a named cursor, %NULL will be returned.
+ *
+ * Returns: (transfer none) (nullable): the texture for cursor or %NULL
+ *   if it is a named cursor
 */
 GdkTexture *
 gdk_cursor_get_texture (GdkCursor *cursor)
@@ -425,15 +428,16 @@ gdk_cursor_get_texture (GdkCursor *cursor)
 }

 /**
- * gdk_cursor_get_hotspot_x:
- * @cursor: a #GdkCursor.
+ * gdk_cursor_get_hotspot_x: (attributes org.gtk.Method.get_property=hotspot-x)
+ * @cursor: a `GdkCursor`
 *
- * Returns the horizontal offset of the hotspot. The hotspot indicates the
- * pixel that will be directly above the cursor.
+ * Returns the horizontal offset of the hotspot.
+ *
+ * The hotspot indicates the pixel that will be directly above the cursor.
 *
 * Note that named cursors may have a nonzero hotspot, but this function
 * will only return the hotspot position for cursors created with
- * gdk_cursor_new_from_texture().
+ * [ctor@Gdk.Cursor.new_from_texture].
 *
 * Returns: the horizontal offset of the hotspot or 0 for named cursors
 */
@@ -446,15 +450,16 @@ gdk_cursor_get_hotspot_x (GdkCursor *cursor)
 }

 /**
- * gdk_cursor_get_hotspot_y:
- * @cursor: a #GdkCursor.
+ * gdk_cursor_get_hotspot_y: (attributes org.gtk.Method.get_property=hotspot-y)
+ * @cursor: a `GdkCursor`
 *
- * Returns the vertical offset of the hotspot. The hotspot indicates the
- * pixel that will be directly above the cursor.
+ * Returns the vertical offset of the hotspot.
+ *
+ * The hotspot indicates the pixel that will be directly above the cursor.
 *
 * Note that named cursors may have a nonzero hotspot, but this function
 * will only return the hotspot position for cursors created with
- * gdk_cursor_new_from_texture().
+ * [ctor@Gdk.Cursor.new_from_texture].
 *
 * Returns: the vertical offset of the hotspot or 0 for named cursors
 */
--- a/Show More
+++ b/Show More