4.1.2

With gi-docgen based docs, we can try to go back to
including the docs in the main release tarball.

.gitlab-ci.yml

@@ -24,9 +24,9 @@ variables:
   BACKEND_FLAGS: "-Dx11-backend=true -Dwayland-backend=true -Dbroadway-backend=true"
   FEATURE_FLAGS: "-Dvulkan=enabled -Dcloudproviders=enabled"
   MESON_TEST_TIMEOUT_MULTIPLIER: 3
-  FEDORA_IMAGE: "registry.gitlab.gnome.org/gnome/gtk/fedora:v25"
+  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:
@@ -43,6 +43,7 @@ style-check-diff:
     - .gitlab-ci/run-style-check-diff.sh
 
 .build-fedora-default:
+  extends: .only-default
   image: $FEDORA_IMAGE
   artifacts:
     when: always
@@ -121,6 +122,7 @@ installed-tests:
 
 
 .mingw-defaults:
+  extends: .only-default
   stage: build
   tags:
     - win32-ps
@@ -144,6 +146,32 @@ msys2-mingw64:
     MSYSTEM: "MINGW64"
     CHERE_INVOKING: "yes"
 
+macos:
+  extends: .only-default
+  only:
+    - branches@GNOME/gtk
+  stage: build
+  tags:
+    - macos
+  needs: []
+  before_script:
+    - bash .gitlab-ci/show-execution-environment.sh
+    - pip3 install --user meson==0.56
+    - pip3 install --user ninja
+    - export PATH=/Users/gitlabrunner/Library/Python/3.7/bin:$PATH
+    - export MESON_FORCE_BACKTRACE=1
+  script:
+    - meson -Dx11-backend=false
+            -Dintrospection=disabled
+            -Dcpp_std=c++11
+            -Dpixman:tests=disabled
+            _build
+    - ninja -C _build
+  artifacts:
+    when: always
+    paths:
+      - "${CI_PROJECT_DIR}/_build/meson-logs"
+
 .flatpak-defaults:
   image: $FLATPAK_IMAGE
   stage: flatpak
@@ -262,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

.gitlab-ci/README.md

@@ -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
 

.gitlab-ci/fedora-base.Dockerfile

@@ -1,4 +1,4 @@
-FROM fedora:31
+FROM fedora:33
 
 RUN dnf -y install \
     adwaita-icon-theme \
@@ -65,7 +65,8 @@ RUN dnf -y install \
     libxslt \
     mesa-dri-drivers \
     mesa-libEGL-devel \
-    mesa-libwayland-egl-devel \
+    mesa-libGLES-devel \
+    meson \
     ninja-build \
     pango-devel \
     pcre-devel \
@@ -86,6 +87,3 @@ RUN dnf -y install \
     which \
     xorg-x11-server-Xvfb \
  && dnf clean all
-
-RUN pip3 install meson==0.55.3
-

.gitlab-ci/fedora-docs.Dockerfile

@@ -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}

.gitlab-ci/fedora.Dockerfile

@@ -1,4 +1,4 @@
-FROM registry.gitlab.gnome.org/gnome/gtk/fedora-base:v25
+FROM registry.gitlab.gnome.org/gnome/gtk/fedora-base:v28
 
 # Enable sudo for wheel users
 RUN sed -i -e 's/# %wheel/%wheel/' -e '0,/%wheel/{s/%wheel/# %wheel/}' /etc/sudoers

.gitlab-ci/run-docker.sh

@@ -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

.gitlab-ci/run-tests.sh

@@ -8,7 +8,8 @@ builddir=$1
 backend=$2
 
 # Ignore memory leaks lower in dependencies
-export LSAN_OPTIONS=suppressions=$srcdir/lsan.supp
+export LSAN_OPTIONS=suppressions=$srcdir/lsan.supp:print_suppressions=0
+export G_SLICE=always-malloc
 
 case "${backend}" in
   x11)

.gitlab-ci/show-execution-environment.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+
+set -eux -o pipefail
+
+xcodebuild -version || :
+xcodebuild -showsdks || :
+
+system_profiler SPSoftwareDataType || :

.gitlab/issue_templates/Bug.md

@@ -1,4 +1,13 @@
+<!--
+  Please, read the CONTRIBUTING.md guide on how to file a new issue.
+
+  https://gitlab.gnome.org/GNOME/gtk/-/blob/master/CONTRIBUTING.md
+-->
 ## Steps to reproduce
+<!--
+  Please, explain the sequence of actions necessary to reproduce the
+  bug
+-->
 
  1. ...
  2. ...
@@ -32,5 +41,8 @@
 ## Additional information
 <!--
  - Screenshots or screen recordings are useful for visual errors
+  - Attaching a screenshot or a video without explaining the current
+    behavior and the actions necessary to reproduce the bug will lead
+    to the bug being closed
  - Please report any warning or message printed on the terminal
 -->

.gitlab/issue_templates/Crash.md

@@ -1,4 +1,14 @@
+<!--
+  Please, read the CONTRIBUTING.md guide on how to file a new issue.
+
+  https://gitlab.gnome.org/GNOME/gtk/-/blob/master/CONTRIBUTING.md
+-->
+
 ## Steps to reproduce
+<!--
+  Please, explain the sequence of actions necessary to reproduce the
+  crash
+-->
 
  1. ...
  2. ...

README.md

@@ -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
 -----------------------

build-aux/flatpak/org.gtk.Demo4.json

@@ -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"
                 }
             ]
         },
@@ -100,7 +100,8 @@
             "config-opts" : [
                 "--libdir=/app/lib",
                 "-Denable_vulkan=no",
-                "-Dbuildtype=debugoptimized"
+                "-Dbuildtype=debugoptimized",
+                "-Dprofile=devel"
             ],
             "sources" : [
                 {

build-aux/flatpak/org.gtk.IconBrowser4.json

@@ -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"
                 }
             ]
         },
@@ -100,7 +100,8 @@
             "config-opts" : [
                 "--libdir=/app/lib",
                 "-Denable_vulkan=no",
-                "-Dbuildtype=debugoptimized"
+                "-Dbuildtype=debugoptimized",
+                "-Dprofile=devel"
             ],
             "sources" : [
                 {

build-aux/flatpak/org.gtk.WidgetFactory4.json

@@ -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"
                 }
             ]
         },
@@ -100,7 +100,8 @@
             "config-opts" : [
                 "--libdir=/app/lib",
                 "-Denable_vulkan=no",
-                "-Dbuildtype=debugoptimized"
+                "-Dbuildtype=debugoptimized",
+                "-Dprofile=devel"
             ],
             "sources" : [
                 {

build-aux/meson/dist-theme.py

@@ -0,0 +1,19 @@
+#!/usr/bin/env python3
+
+import os
+from pathlib import PurePath
+import subprocess
+
+stylesheets = [ 'gtk/theme/Adwaita/Adwaita.css',
+                'gtk/theme/Adwaita/Adwaita-dark.css',
+                'gtk/theme/HighContrast/HighContrast.css',
+                'gtk/theme/HighContrast/HighContrast-dark.css' ]
+
+sourceroot = os.environ.get('MESON_SOURCE_ROOT')
+distroot = os.environ.get('MESON_DIST_ROOT')
+
+for stylesheet in stylesheets:
+  stylesheet_path = PurePath(stylesheet)
+  src = PurePath(sourceroot, stylesheet_path.with_suffix('.scss'))
+  dst = PurePath(distroot, stylesheet_path)
+  subprocess.call(['sassc', '-a', '-M', '-t', 'compact', src, dst])

demos/gtk-demo/assistant.c

@@ -98,6 +98,9 @@ create_page1 (GtkWidget *assistant)
   gtk_box_append (GTK_BOX (box), label);
 
   entry = gtk_entry_new ();
+  gtk_accessible_update_relation (GTK_ACCESSIBLE (entry),
+                                  GTK_ACCESSIBLE_RELATION_LABELLED_BY, label, NULL,
+                                  -1);
   gtk_entry_set_activates_default (GTK_ENTRY (entry), TRUE);
   gtk_widget_set_valign (entry, GTK_ALIGN_CENTER);
   gtk_box_append (GTK_BOX (box), entry);

demos/gtk-demo/fishbowl.c

@@ -119,13 +119,12 @@ create_label (void)
 static GtkWidget *
 create_video (void)
 {
-  GtkMediaStream *stream = gtk_media_file_new_for_resource ("/images/gtk-logo.webm");
-  GtkWidget *w = gtk_picture_new_for_paintable (GDK_PAINTABLE (stream));
+  GtkWidget *w = gtk_video_new ();
 
   gtk_widget_set_size_request (w, 64, 64);
-  gtk_media_stream_set_loop (stream, TRUE);
-  gtk_media_stream_play (stream);
-  g_object_unref (stream);
+  gtk_video_set_loop (GTK_VIDEO (w), TRUE);
+  gtk_video_set_autoplay (GTK_VIDEO (w), TRUE);
+  gtk_video_set_resource (GTK_VIDEO (w), "/images/gtk-logo.webm");
 
   return w;
 }

demos/gtk-demo/gtkgears.c

@@ -787,6 +787,8 @@ gtk_gears_realize (GtkWidget *widget)
   glLinkProgram(program);
   glGetProgramInfoLog(program, sizeof msg, NULL, msg);
   g_debug ("program info: %s\n", msg);
+  glDetachShader (program, v);
+  glDetachShader (program, f);
   glDeleteShader (v);
   glDeleteShader (f);
 

demos/gtk-demo/iconscroll.c

@@ -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;

demos/gtk-demo/listview_applauncher.c

@@ -39,7 +39,7 @@ create_application_list (void)
 }
 
 /* This is the function we use for setting up new listitems to display.
- * We add just an #GtkImage and a #GtkKabel here to display the application's
+ * We add just an #GtkImage and a #GtkLabel here to display the application's
  * icon and name, as this is just a simple demo.
  */
 static void

demos/gtk-demo/main.c

@@ -25,6 +25,8 @@
 #include "demos.h"
 #include "fontify.h"
 
+#include "demo_conf.h"
+
 static GtkWidget *info_view;
 static GtkWidget *source_view;
 
@@ -196,16 +198,20 @@ activate_about (GSimpleAction *action,
                           gtk_get_micro_version ());
   g_string_append_printf (s, "\nA link can appear here: <http://www.gtk.org>");
 
-  version = g_strdup_printf ("%s\nRunning against GTK %d.%d.%d",
+  version = g_strdup_printf ("%s%s%s\nRunning against GTK %d.%d.%d",
                              PACKAGE_VERSION,
+                             g_strcmp0 (PROFILE, "devel") == 0 ? "-" : "",
+                             g_strcmp0 (PROFILE, "devel") == 0 ? VCS_TAG : "",
                              gtk_get_major_version (),
                              gtk_get_minor_version (),
                              gtk_get_micro_version ());
 
   gtk_show_about_dialog (GTK_WINDOW (gtk_application_get_active_window (app)),
-                         "program-name", "GTK Demo",
+                         "program-name", g_strcmp0 (PROFILE, "devel") == 0
+                                         ? "GTK Demo (Development)"
+                                         : "GTK Demo",
                          "version", version,
-                         "copyright", "© 1997—2020 The GTK Team",
+                         "copyright", "© 1997—2021 The GTK Team",
                          "license-type", GTK_LICENSE_LGPL_2_1,
                          "website", "http://www.gtk.org",
                          "comments", "Program to demonstrate GTK widgets",
@@ -901,6 +907,9 @@ activate (GApplication *app)
   window = (GtkWidget *)gtk_builder_get_object (builder, "window");
   gtk_application_add_window (GTK_APPLICATION (app), GTK_WINDOW (window));
 
+  if (g_strcmp0 (PROFILE, "devel") == 0)
+    gtk_widget_add_css_class (window, "devel");
+
   action = g_simple_action_new ("run", NULL);
   g_signal_connect (action, "activate", G_CALLBACK (activate_run), window);
   g_action_map_add_action (G_ACTION_MAP (window), G_ACTION (action));
@@ -1043,10 +1052,10 @@ out:
 static void
 print_version (void)
 {
-  g_print ("gtk4-demo %d.%d.%d\n",
-           gtk_get_major_version (),
-           gtk_get_minor_version (),
-           gtk_get_micro_version ());
+  g_print ("gtk4-demo %s%s%s\n",
+           PACKAGE_VERSION,
+           g_strcmp0 (PROFILE, "devel") == 0 ? "-" : "",
+           g_strcmp0 (PROFILE, "devel") == 0 ? VCS_TAG : "");
 }
 
 static int

demos/gtk-demo/meson.build

@@ -167,6 +167,8 @@ foreach flag: common_cflags
   endif
 endforeach
 
+gtkdemo_deps += [ demo_conf_h ]
+
 executable('gtk4-demo',
   sources: [demos, demos_h, extra_demo_sources, gtkdemo_resources],
   c_args: gtkdemo_args + demo_cflags,

demos/icon-browser/iconbrowserapp.c

@@ -4,6 +4,8 @@
 #include "iconbrowserapp.h"
 #include "iconbrowserwin.h"
 
+#include "demo_conf.h"
+
 struct _IconBrowserApp
 {
   GtkApplication parent;
@@ -75,21 +77,25 @@ about_activated (GSimpleAction *action,
                           gtk_get_minor_version (),
                           gtk_get_micro_version ());
   g_string_append_printf (s, "\nIcon theme\n\t%s", icon_theme);
-  version = g_strdup_printf ("%s\nRunning against GTK %d.%d.%d",
+  version = g_strdup_printf ("%s%s%s\nRunning against GTK %d.%d.%d",
                              PACKAGE_VERSION,
+                             g_strcmp0 (PROFILE, "devel") == 0 ? "-" : "",
+                             g_strcmp0 (PROFILE, "devel") == 0 ? VCS_TAG : "",
                              gtk_get_major_version (),
                              gtk_get_minor_version (),
                              gtk_get_micro_version ());
 
   gtk_show_about_dialog (GTK_WINDOW (gtk_application_get_active_window (app)),
-                         "program-name", "GTK Icon Browser",
+                         "program-name", g_strcmp0 (PROFILE, "devel") == 0
+                                         ? "GTK Icon Browser (Development)"
+                                         : "GTK Icon Browser",
                          "version", version,
-                         "copyright", "© 1997—2020 The GTK Team",
+                         "copyright", "© 1997—2021 The GTK Team",
                          "license-type", GTK_LICENSE_LGPL_2_1,
                          "website", "http://www.gtk.org",
                          "comments", "Program to browse themed icons",
                          "authors", authors,
-                         "logo-icon-name", "org.gtk.Demo4",
+                         "logo-icon-name", "org.gtk.IconBrowser4",
                          "title", "About GTK Icon Browser",
                          "system-information", s->str,
                          NULL);
@@ -129,6 +135,10 @@ icon_browser_app_activate (GApplication *app)
   IconBrowserWindow *win;
 
   win = icon_browser_window_new (ICON_BROWSER_APP (app));
+
+  if (g_strcmp0 (PROFILE, "devel") == 0)
+    gtk_widget_add_css_class (GTK_WIDGET (win), "devel");
+
   gtk_window_present (GTK_WINDOW (win));
 }
 

demos/icon-browser/iconbrowserwin.c

@@ -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;
@@ -279,11 +281,31 @@ drag_prepare_texture (GtkDragSource *source,
                       GtkWidget     *widget)
 {
   GdkPaintable *paintable = get_image_paintable (GTK_IMAGE (widget));
+  GtkSnapshot *snapshot;
+  double width, height;
+  GskRenderNode *node;
+  GskRenderer *renderer;
+  GdkTexture *texture;
+  GdkContentProvider *ret;
 
   if (!GDK_IS_PAINTABLE (paintable))
     return NULL;
 
-  return gdk_content_provider_new_typed (GDK_TYPE_PAINTABLE, paintable);
+  snapshot = gtk_snapshot_new ();
+  width = gdk_paintable_get_intrinsic_width (paintable);
+  height = gdk_paintable_get_intrinsic_height (paintable);
+  gdk_paintable_snapshot (paintable, snapshot, width, height);
+  node = gtk_snapshot_free_to_node (snapshot);
+
+  renderer = gtk_native_get_renderer (gtk_widget_get_native (widget));
+  texture = gsk_renderer_render_texture (renderer, node, &GRAPHENE_RECT_INIT (0, 0, width, height));
+
+  ret = gdk_content_provider_new_typed (GDK_TYPE_TEXTURE, texture);
+
+  g_object_unref (texture);
+  gsk_render_node_unref (node);
+
+  return ret;
 }
 
 static GdkContentProvider *
@@ -334,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)
 {
@@ -360,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
@@ -389,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);
@@ -402,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);

demos/icon-browser/meson.build

@@ -14,7 +14,7 @@ iconbrowser_resources = gnome.compile_resources('iconbrowser_resources',
 executable('gtk4-icon-browser',
   sources: [iconbrowser_sources, iconbrowser_resources],
   c_args: common_cflags,
-  dependencies: libgtk_dep,
+  dependencies: [ libgtk_dep, demo_conf_h ],
   include_directories: confinc,
   gui_app: true,
   link_args: extra_demo_ldflags,

demos/icon-browser/window.ui

@@ -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>

demos/meson.build

@@ -1,3 +1,19 @@
+demo_conf = configuration_data()
+demo_conf.set_quoted('PROFILE', get_option('profile'))
+demo_conf.set_quoted('VCS_TAG', '@VCS_TAG@')
+
+demo_conf_h = declare_dependency(
+  sources: vcs_tag(
+             command: [ 'git', 'rev-parse', '--short', 'HEAD' ],
+             fallback: get_option('profile') != 'default' ? 'devel' : '',
+             input: configure_file(
+                      output: 'demo_conf.h.in',
+                      configuration: demo_conf
+                    ),
+             output: 'demo_conf.h'
+           )
+)
+
 subdir('constraint-editor')
 subdir('gtk-demo')
 subdir('icon-browser')

demos/node-editor/help-window.ui

@@ -13,6 +13,7 @@
             <property name="right-margin">20</property>
             <property name="top-margin">20</property>
             <property name="bottom-margin">20</property>
+            <property name="monospace">1</property>
             <property name="buffer">
               <object class="GtkTextBuffer" id="buffer"/>
             </property>

demos/node-editor/meson.build

@@ -12,7 +12,7 @@ node_editor_resources = gnome.compile_resources('node_editor_resources',
 
 executable('gtk4-node-editor',
   sources: [node_editor_sources, node_editor_resources],
-  dependencies: libgtk_dep,
+  dependencies: [ libgtk_dep, demo_conf_h ],
   include_directories: confinc,
   c_args: [
     '-DNODE_EDITOR_SOURCE_DIR="@0@/../../testsuite/gsk/compare/"'.format(meson.current_source_dir())

demos/node-editor/node-editor-application.c

@@ -23,6 +23,8 @@
 
 #include "node-editor-window.h"
 
+#include "demo_conf.h"
+
 static const char *css =
 "textview.editor {"
 "  color: rgb(192, 197, 206);"
@@ -94,22 +96,26 @@ activate_about (GSimpleAction *action,
 
   g_string_append_printf (s, "\nRenderer\n\t%s", renderer);
 
-  version = g_strdup_printf ("%s\nRunning against GTK %d.%d.%d",
+  version = g_strdup_printf ("%s%s%s\nRunning against GTK %d.%d.%d",
                              PACKAGE_VERSION,
+                             g_strcmp0 (PROFILE, "devel") == 0 ? "-" : "",
+                             g_strcmp0 (PROFILE, "devel") == 0 ? VCS_TAG : "",
                              gtk_get_major_version (),
                              gtk_get_minor_version (),
                              gtk_get_micro_version ());
 
   dialog = g_object_new (GTK_TYPE_ABOUT_DIALOG,
                          "transient-for", gtk_application_get_active_window (app),
-                         "program-name", "GTK Node Editor",
+                         "program-name", g_strcmp0 (PROFILE, "devel") == 0
+                                         ? "GTK Node Editor (Development)"
+                                         : "GTK Node Editor",
                          "version", version,
-                         "copyright", "© 2019—2020 The GTK Team",
+                         "copyright", "© 2019—2021 The GTK Team",
                          "license-type", GTK_LICENSE_LGPL_2_1,
                          "website", "http://www.gtk.org",
                          "comments", "Program to test GTK rendering",
                          "authors", (const char *[]){ "Benjamin Otte", "Timm Bäder", NULL},
-                         "logo-icon-name", "org.gtk.gtk4.NodeEditor.Devel",
+                         "logo-icon-name", "org.gtk.gtk4.NodeEditor",
                          "title", "About GTK Node Editor",
                          "system-information", s->str,
                          NULL);
@@ -207,6 +213,10 @@ node_editor_application_activate (GApplication *app)
   NodeEditorWindow *win;
 
   win = node_editor_window_new (NODE_EDITOR_APPLICATION (app));
+
+  if (g_strcmp0 (PROFILE, "devel") == 0)
+    gtk_widget_add_css_class (GTK_WIDGET (win), "devel");
+
   gtk_window_present (GTK_WINDOW (win));
 }
 

demos/node-editor/node-editor-window.c

@@ -25,6 +25,7 @@
 
 #include "gsk/gskrendernodeparserprivate.h"
 #include "gsk/gl/gskglrenderer.h"
+#include "gsk/ngl/gsknglrenderer.h"
 #ifdef GDK_WINDOWING_BROADWAY
 #include "gsk/broadway/gskbroadwayrenderer.h"
 #endif
@@ -700,6 +701,16 @@ out:
   g_free (source_dir);
 }
 
+static void
+dark_mode_cb (GtkToggleButton *button,
+              GParamSpec      *pspec,
+              NodeEditorWindow *self)
+{
+  g_object_set (gtk_widget_get_settings (GTK_WIDGET (self)),
+                "gtk-application-prefer-dark-theme", gtk_toggle_button_get_active (button),
+                NULL);
+}
+
 static void
 node_editor_window_finalize (GObject *object)
 {
@@ -752,6 +763,9 @@ node_editor_window_realize (GtkWidget *widget)
   node_editor_window_add_renderer (self,
                                    gsk_gl_renderer_new (),
                                    "OpenGL");
+  node_editor_window_add_renderer (self,
+                                   gsk_ngl_renderer_new (),
+                                   "NGL");
 #ifdef GDK_RENDERING_VULKAN
   node_editor_window_add_renderer (self,
                                    gsk_vulkan_renderer_new (),
@@ -814,6 +828,7 @@ node_editor_window_class_init (NodeEditorWindowClass *class)
   gtk_widget_class_bind_template_callback (widget_class, export_image_cb);
   gtk_widget_class_bind_template_callback (widget_class, testcase_save_clicked_cb);
   gtk_widget_class_bind_template_callback (widget_class, testcase_name_entry_changed_cb);
+  gtk_widget_class_bind_template_callback (widget_class, dark_mode_cb);
 }
 
 static GtkWidget *
@@ -910,6 +925,26 @@ node_editor_window_init (NodeEditorWindow *self)
   self->text_buffer = gtk_text_buffer_new (self->tag_table);
   g_signal_connect (self->text_buffer, "changed", G_CALLBACK (text_changed), self);
   gtk_text_view_set_buffer (GTK_TEXT_VIEW (self->text_view), self->text_buffer);
+
+  /* Default */
+  gtk_text_buffer_set_text (self->text_buffer,
+         "shadow {\n"
+         "  child: texture {\n"
+         "    bounds: 0 0 128 128;\n"
+         "    texture: url(\"resource:///org/gtk/gtk4/node-editor/icons/apps/org.gtk.gtk4.NodeEditor.svg\");\n"
+         "  }\n"
+         "  shadows: rgba(0,0,0,0.5) 0 1 12;\n"
+         "}\n"
+         "\n"
+         "transform {\n"
+         "  child: text {\n"
+         "    color: rgb(46,52,54);\n"
+         "    font: \"Cantarell Bold 11\";\n"
+         "    glyphs: \"GTK Node Editor\";\n"
+         "    offset: 8 14.418;\n"
+         "  }\n"
+         "  transform: translate(0, 140);\n"
+         "}", -1);
 }
 
 NodeEditorWindow *

demos/node-editor/node-editor-window.ui

@@ -139,6 +139,15 @@
             <property name="icon-name">open-menu-symbolic</property>
           </object>
         </child>
+        <child type="end">
+          <object class="GtkToggleButton" id="dark_bg_button">
+            <property name="valign">center</property>
+            <property name="has-frame">0</property>
+            <property name="icon-name">display-brightness-symbolic</property>
+            <property name="tooltip-text" translatable="yes">Use a dark background</property>
+            <signal name="notify::active" handler="dark_mode_cb" swapped="0"/>
+          </object>
+        </child>
       </object>
     </child>
     <child>

demos/node-editor/node-editor.gresource.xml

@@ -4,6 +4,6 @@
     <file preprocess="xml-stripblanks">node-editor-window.ui</file>
     <file preprocess="xml-stripblanks">help-window.ui</file>
     <file>node-format.md</file>
-    <file alias='icons/apps/org.gtk.gtk4.NodeEditor.Devel.svg'>data/scalable/apps/org.gtk.gtk4.NodeEditor.Devel.svg</file>
+    <file alias='icons/apps/org.gtk.gtk4.NodeEditor.svg'>data/scalable/apps/org.gtk.gtk4.NodeEditor.svg</file>
   </gresource>
 </gresources>

demos/node-editor/node-format.md

@@ -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.
 

demos/print-editor/meson.build

@@ -1,7 +1,7 @@
 executable('gtk4-print-editor',
   sources: ['print-editor.c'],
   c_args: common_cflags,
-  dependencies: libgtk_dep,
+  dependencies: [ libgtk_dep, demo_conf_h ],
   include_directories: confinc,
   gui_app: true,
   link_args: extra_demo_ldflags,

demos/print-editor/org.gtk.PrintEditor4.desktop

@@ -2,7 +2,7 @@
 Name=Print Editor
 Comment=A simple editor demonstrating GTK printing
 Exec=gtk4-print-editor %f
-Icon=org.gtk.PrintEditor4.Devel
+Icon=org.gtk.PrintEditor4
 Terminal=false
 Type=Application
 StartupNotify=true

demos/print-editor/print-editor.c

@@ -4,6 +4,8 @@
 #include <glib/gi18n.h>
 #include <gtk/gtk.h>
 
+#include "demo_conf.h"
+
 static GtkWidget *main_window;
 static GFile *filename = NULL;
 static GtkPageSetup *page_setup = NULL;
@@ -641,22 +643,26 @@ activate_about (GSimpleAction *action,
   g_strfreev (backends);
   g_free (setting);
 
-  version = g_strdup_printf ("%s\nRunning against GTK %d.%d.%d",
+  version = g_strdup_printf ("%s%s%s\nRunning against GTK %d.%d.%d",
                              PACKAGE_VERSION,
+                             g_strcmp0 (PROFILE, "devel") == 0 ? "-" : "",
+                             g_strcmp0 (PROFILE, "devel") == 0 ? VCS_TAG : "",
                              gtk_get_major_version (),
                              gtk_get_minor_version (),
                              gtk_get_micro_version ());
 
   dialog = g_object_new (GTK_TYPE_ABOUT_DIALOG,
                          "transient-for", main_window,
-                         "program-name", "GTK Print Editor",
+                         "program-name", g_strcmp0 (PROFILE, "devel") == 0
+                                         ? "GTK Print Editor (Development)"
+                                         : "GTK Print Editor",
                          "version", version,
-                         "copyright", "© 2006-2020 Red Hat, Inc",
+                         "copyright", "© 2006-2021 Red Hat, Inc",
                          "license-type", GTK_LICENSE_LGPL_2_1,
                          "website", "http://www.gtk.org",
                          "comments", "Program to demonstrate GTK printing",
                          "authors", authors,
-                         "logo-icon-name", "org.gtk.PrintEditor4.Devel",
+                         "logo-icon-name", "org.gtk.PrintEditor4",
                          "title", "About GTK Print Editor",
                          "system-information", sysinfo->str,
                          NULL);
@@ -807,6 +813,10 @@ activate (GApplication *app)
   GtkWidget *contents;
 
   main_window = gtk_application_window_new (GTK_APPLICATION (app));
+
+  if (g_strcmp0 (PROFILE, "devel") == 0)
+    gtk_widget_add_css_class (GTK_WIDGET (main_window), "devel");
+
   gtk_window_set_icon_name (GTK_WINDOW (main_window), "text-editor");
   gtk_window_set_default_size (GTK_WINDOW (main_window), 400, 600);
   gtk_application_window_set_show_menubar (GTK_APPLICATION_WINDOW (main_window), TRUE);

demos/widget-factory/meson.build

@@ -8,7 +8,7 @@ widgetfactory_resources = gnome.compile_resources('widgetfactory_resources',
 executable('gtk4-widget-factory',
   sources: ['widget-factory.c', widgetfactory_resources],
   c_args: common_cflags,
-  dependencies: libgtk_dep,
+  dependencies: [ libgtk_dep, demo_conf_h ],
   include_directories: confinc,
   gui_app: true,
   link_args: extra_demo_ldflags,

demos/widget-factory/widget-factory.c

@@ -25,6 +25,8 @@
 #include <glib/gi18n.h>
 #include <gtk/gtk.h>
 
+#include "demo_conf.h"
+
 static void
 change_dark_state (GSimpleAction *action,
                     GVariant      *state,
@@ -300,8 +302,10 @@ activate_about (GSimpleAction *action,
                           gtk_get_micro_version ());
   g_string_append_printf (s, "\nA link can appear here: <http://www.gtk.org>");
 
-  version = g_strdup_printf ("%s\nRunning against GTK %d.%d.%d",
+  version = g_strdup_printf ("%s%s%s\nRunning against GTK %d.%d.%d",
                              PACKAGE_VERSION,
+                             g_strcmp0 (PROFILE, "devel") == 0 ? "-" : "",
+                             g_strcmp0 (PROFILE, "devel") == 0 ? VCS_TAG : "",
                              gtk_get_major_version (),
                              gtk_get_minor_version (),
                              gtk_get_micro_version ());
@@ -309,9 +313,11 @@ activate_about (GSimpleAction *action,
   dialog = g_object_new (GTK_TYPE_ABOUT_DIALOG,
                          "transient-for", gtk_application_get_active_window (app),
                          "modal", TRUE,
-                         "program-name", "GTK Widget Factory",
+                         "program-name", g_strcmp0 (PROFILE, "devel") == 0
+                                         ? "GTK Widget Factory (Development)"
+                                         : "GTK Widget Factory",
                          "version", version,
-                         "copyright", "© 1997—2020 The GTK Team",
+                         "copyright", "© 1997—2021 The GTK Team",
                          "license-type", GTK_LICENSE_LGPL_2_1,
                          "website", "http://www.gtk.org",
                          "comments", "Program to demonstrate GTK themes and widgets",
@@ -2065,6 +2071,10 @@ activate (GApplication *app)
     }
 
   window = (GtkWindow *)gtk_builder_get_object (builder, "window");
+
+  if (g_strcmp0 (PROFILE, "devel") == 0)
+    gtk_widget_add_css_class (GTK_WIDGET (window), "devel");
+
   gtk_application_add_window (GTK_APPLICATION (app), window);
   g_action_map_add_action_entries (G_ACTION_MAP (window),
                                    win_entries, G_N_ELEMENTS (win_entries),
@@ -2319,10 +2329,10 @@ activate (GApplication *app)
 static void
 print_version (void)
 {
-  g_print ("gtk4-widget-factory %d.%d.%d\n",
-           gtk_get_major_version (),
-           gtk_get_minor_version (),
-           gtk_get_micro_version ());
+  g_print ("gtk4-widget-factory %s%s%s\n",
+           PACKAGE_VERSION,
+           g_strcmp0 (PROFILE, "devel") == 0 ? "-" : "",
+           g_strcmp0 (PROFILE, "devel") == 0 ? VCS_TAG : "");
 }
 
 static int

demos/widget-factory/widget-factory.ui

@@ -3298,7 +3298,6 @@ bad things might happen.</property>
       </object>
     </child>
   </object>
-  <object class="GtkSizeGroup" id="basement-indicators"/>
   <menu id="new_style_menu_model">
     <section>
       <attribute name="display-hint">circular-buttons</attribute>

docs/CODING-STYLE.md

@@ -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).
 

docs/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

docs/reference/gdk/cairo.md

@@ -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/).

docs/reference/gdk/gdk4-docs.xml

@@ -1,85 +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-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>

docs/reference/gdk/gdk4-overrides.txt

@@ -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>

docs/reference/gdk/gdk4-wayland.toml.in

@@ -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/"

docs/reference/gdk/gdk4-x11.toml.in

@@ -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/"

docs/reference/gdk/gdk4.toml.in

@@ -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"

docs/reference/gdk/gdk4.types

@@ -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

docs/reference/gdk/general.md

@@ -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.

docs/reference/gdk/images/gtk-logo.svg

@@ -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>

docs/reference/gdk/keys.md

@@ -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`.

docs/reference/gdk/macos.md

@@ -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`.

docs/reference/gdk/meson.build

@@ -1,187 +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',
-]
-
-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

docs/reference/gdk/pango.md

@@ -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)

docs/reference/gdk/urlmap.js

@@ -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/' ],
+]

docs/reference/gdk/version.xml.in

@@ -1 +0,0 @@
-@GTK_VERSION@

docs/reference/gdk/wayland.md

@@ -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`.

docs/reference/gdk/x11.md

@@ -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`.

docs/reference/gsk/gsk4-docs.xml

@@ -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>

docs/reference/gsk/gsk4-sections.txt

@@ -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>

docs/reference/gsk/gsk4.toml.in

@@ -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"

docs/reference/gsk/gsk4.types

@@ -1,3 +0,0 @@
-gsk_render_node_get_type
-gsk_renderer_get_type
-gsk_gl_shader_get_type

docs/reference/gsk/gtk-logo.svg

@@ -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>

docs/reference/gsk/meson.build

@@ -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

docs/reference/gsk/urlmap.js

@@ -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/' ],
+]

docs/reference/gsk/version.xml.in

@@ -1 +0,0 @@
-@GTK_VERSION@

docs/reference/gtk/actions.md

@@ -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):

docs/reference/gtk/broadway.md

@@ -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

docs/reference/gtk/building.md

@@ -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

docs/reference/gtk/compiling.md

@@ -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

docs/reference/gtk/css-overview.md

@@ -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,

docs/reference/gtk/css-properties.md

@@ -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
@@ -32,7 +36,7 @@ not quite the same as the CSS definition of rem.
 The calc() notation adds considerable expressive power. There are limits
 on what types can be combined in such an expression (e.g. it does not make
 sense to add a number and a time). For the full details, see the
-[CSS3 VAlues and Units](https://www.w3.org/TR/css3-values/#calc-notation)
+[CSS3 Values and Units](https://www.w3.org/TR/css3-values/#calc-notation)
 spec.
 
 A common pattern among shorthand properties (called 'four sides') is one
@@ -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
 
@@ -151,7 +158,7 @@ done with
 |caret-color|[CSS Basic User Interface Level 3](https://www.w3.org/TR/css3-ui/#caret-color) | CSS allows an auto value |
 |-gtk-secondary-caret-color|[Color](https://www.w3.org/TR/css-color-3/#valuea-def-color) | used for the secondary caret in bidirectional text |
 |letter-spacing| [CSS Text Level 3](https://www.w3.org/TR/css3-text/#letter-spacing) | |
-|text-decoration-line| [CSS Text Decoration Level 3](https://www.w3.org/TR/css-text-decor-3/#text-decoration-line-property) | CSS allows overline |
+|text-decoration-line| [CSS Text Decoration Level 3](https://www.w3.org/TR/css-text-decor-3/#text-decoration-line-property) | |
 |text-decoration-color| [CSS Text Decoration Level 3](https://www.w3.org/TR/css-text-decor-3/#text-decoration-color-property) | |
 |text-decoration-style| [CSS Text Decoration Level 3](https://www.w3.org/TR/css-text-decor-3/#text-decoration-style-property) | CSS allows dashed and dotted |
 |text-shadow| [CSS Text Decoration Level 3](https://www.w3.org/TR/css-text-decor-3/#text-shadow-property) | |
@@ -159,11 +166,12 @@ done with
 |-gtk-icon-source| [Image](https://www.w3.org/TR/css-backgrounds-3/#typedef-image), `builtin` or `none` | used for builtin icons in buttons and expanders |
 |-gtk-icon-size| [Length](https://www.w3.org/TR/css3-values/#length-value) | size used for builtin icons in buttons and expanders |
 |-gtk-icon-style| `requested`, `regular` or `symbolic` | preferred style for application-loaded icons |
-|-gtk-icon-transform| [Transform list](https://drafts.csswg.org/css-transforms-1/#typedef-transform-list) or `none` | applied to builtin and application-loaded icons |
+|-gtk-icon-transform| [Transform list](https://www.w3.org/TR/css-transforms-1/#typedef-transform-list) or `none` | applied to builtin and application-loaded icons |
 |-gtk-icon-palette| Color palette, as explained above | used to recolor symbolic icons |
 |-gtk-icon-shadow| [Shadow](https://www.w3.org/TR/css-backgrounds-3/#typedef-shadow) or `none` | applied to builtin and application-loaded icons |
 |-gtk-icon-filter| [Filter value list](https://www.w3.org/TR/filter-effects-1/#typedef-filter-value-list) or `none` | applied to builtin and application-loaded icons |
-|transform| [CSS Transforms Level 2](https://drafts.csswg.org/css-transforms-2/) | |
+|transform| [CSS Transforms Level 1](https://www.w3.org/TR/css-transforms-1/#transform-property) | |
+|transform-origin| [CSS Transforms Level 1](https://www.w3.org/TR/css-transforms-1/#transform-origin-property) | CSS allows specifying a z component|
 |min-width| [CSS Box Model Level 3](https://www.w3.org/TR/css3-box/#min-width) | CSS allows percentages |
 |min-height| [CSS Box Model Level 3](https://www.w3.org/TR/css3-box/#min-height) | CSS allows percentages |
 |margin-top| [CSS Box Model Level 3](https://www.w3.org/TR/css3-box/#margin-top) | CSS allows percentages or auto |
@@ -217,7 +225,7 @@ done with
 |background-size| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#background-size) | |
 |background-position| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#background-position) | |
 |background-repeat| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#background-repeat) | |
-|background-image| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#background-image) | not supported: urls without quotes, colors in crossfades |
+|background-image| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#background-image) | not supported: urls without quotes |
 |box-shadow| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#box-shadow) | |
 |background-blend-mode| [CSS Compositing and Blending Level 1](https://www.w3.org/TR/compositing-1/#propdef-background-blend-mode) | only affects multiple backgrounds |
 |background| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#background) | |
@@ -235,4 +243,4 @@ done with
 |animation-delay| [CSS Animations Level 1](https://www.w3.org/TR/css3-animations/#animation-delay) | |
 |animation-fill-mode| [CSS Animations Level 1](https://www.w3.org/TR/css3-animations/#animation-fill-mode) | |
 |animation| [CSS Animations Level 1](https://www.w3.org/TR/css3-animations/#animation) | |
-|border-spacing| [CSS Table Level 3](https://www.w3.org/TR/css-tables-3/#border-spacing-property) | respected by GtkBox and GtkGrid |
+|border-spacing| [CSS Table Level 3](https://www.w3.org/TR/css-tables-3/#border-spacing-property) | respected by GtkBoxLayout, GtkGridLayout, GtkCenterLayout |

docs/reference/gtk/drawing-model.md

@@ -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

docs/reference/gtk/getting_started.md

@@ -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,29 +346,28 @@ 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
-widget to use. It offers a canvas on which you can draw by connecting to
-the ::draw signal.
+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 part or all of the widget to be redrawn, by calling
-gtk_widget_queue_draw() or its variants. GTK takes care of most of the
-details by providing a ready-to-use cairo context to the ::draw signal
-handler.
+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.
 
-The following example shows a ::draw signal handler. It is a bit more
-complicated than the previous examples, since it also demonstrates
-input event handling by means of event controllers.
+The following example shows how to use a draw function with GtkDrawingArea.
+It is a bit more complicated than the previous examples, since it also
+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 */
@@ -557,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
@@ -568,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>
 
@@ -638,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">
@@ -682,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
@@ -708,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"
@@ -759,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"
@@ -834,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"
@@ -878,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
@@ -906,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">
@@ -926,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
@@ -951,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
@@ -959,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">
@@ -976,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:
@@ -990,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
@@ -1021,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
@@ -1064,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:
 
@@ -1085,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">
@@ -1113,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
@@ -1163,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:
 
@@ -1179,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">
@@ -1208,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
@@ -1233,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
@@ -1240,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">
@@ -1320,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"
@@ -1385,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
@@ -1403,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
@@ -1413,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">
@@ -1475,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
@@ -1522,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:
@@ -1531,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">
@@ -1606,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">
@@ -1631,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
@@ -1654,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:
@@ -1665,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
@@ -1674,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">
@@ -1711,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
@@ -1730,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,

docs/reference/gtk/gtk-markdown-to-docbook

@@ -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)

docs/reference/gtk/gtk4-builder-tool.xml

@@ -41,35 +41,41 @@
   <command>gtk4-builder-tool</command> can perform various operations
   on GtkBuilder .ui files.
 </para>
+<para>
+  The <option>validate</option> command validates the .ui file and reports
+  errors to stderr.
+</para>
+<para>
+  The <option>enumerate</option> command lists all the named objects that
+  are created in the .ui file.
+</para>
+<para>
+  The <option>preview</option> command displays the .ui file. This command
+  accepts options to specify the ID of the toplevel object and a .css file
+  to use.
+</para>
+<para>
+  The <option>simplify</option> command simplifies the .ui file by removing
+  properties that are set to their default values and writes the resulting XML
+  to stdout, or back to the input file.
+</para>
+<para>
+  When the <option>--3to4</option> is specified, <option>simplify</option>
+  interprets the input as a GTK 3 ui file and attempts to convert it to GTK 4
+  equivalents. It performs various conversions, such as renaming properties,
+  translating child properties to layout properties, rewriting the setup for
+  GtkNotebook, GtkStack, GtkAssistant  or changing toolbars into boxes.
+</para>
 <para>
   You should always test the modified .ui files produced by gtk4-builder-tool
   before using them in production.
 </para>
-</refsect1>
-
-<refsect1><title>Commands</title>
-  <para>The following commands are understood:</para>
-  <variablelist>
-    <varlistentry>
-    <term><option>validate</option></term>
-      <listitem><para>Validates the .ui file and report errors to stderr.</para></listitem>
-    </varlistentry>
-    <varlistentry>
-    <term><option>simplify</option></term>
-      <listitem><para>Simplifies the .ui file by removing properties that
-      are set to their default values and write the resulting XML to stdout,
-      or back to the input file.</para></listitem>
-    </varlistentry>
-    <varlistentry>
-    <term><option>enumerate</option></term>
-      <listitem><para>Lists all the named objects that are created in the .ui file.</para></listitem>
-    </varlistentry>
-    <varlistentry>
-    <term><option>preview</option></term>
-      <listitem><para>Preview the .ui file. This command accepts options
-                to specify the ID of an object and a .css file to use.</para></listitem>
-    </varlistentry>
-  </variablelist>
+<para>
+  Note in particular that the conversion
+  done with <option>--3to4</option> is meant as a starting point for a port
+  from GTK 3 to GTK 4. It is expected that you will have to do manual fixups
+  after the initial conversion.
+</para>
 </refsect1>
 
 <refsect1><title>Simplify Options</title>

docs/reference/gtk/gtk4-docs.xml

@@ -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>

docs/reference/gtk/gtk4-encode-symbolic-svg.xml

@@ -61,6 +61,13 @@
     <listitem><para>Write png files to <replaceable>DIRECTORY</replaceable>
          instead of the current working directory.</para></listitem>
   </varlistentry>
+  <varlistentry>
+    <term>--debug</term>
+    <listitem><para>Generate png files of the various channels during
+         the conversion. If these files are not monochrome green, they
+         are often helpful in pinpointing the problematic parts of
+         the source svg.</para></listitem>
+  </varlistentry>
 </variablelist>
 </refsect1>
 

docs/reference/gtk/gtk4.toml.in

@@ -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"

docs/reference/gtk/gtk4.types.in

@@ -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

docs/reference/gtk/images/gtk-logo.svg

@@ -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>

docs/reference/gtk/initialization.md

@@ -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

docs/reference/gtk/input-handling.md

@@ -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
 

docs/reference/gtk/meson.build

@@ -1,482 +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/popup-anchors.png',
-  'images/popup-at.svg',
-  'images/popup-flip.png',
-  'images/popup-slide.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',
@@ -493,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
 

docs/reference/gtk/migrating-2to4.md

@@ -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)