Merge tag 'upstream/2.80.0' into packaging/openkylin/nile

Upstream version 2.80.0

.gitlab-ci.yml

@@ -11,18 +11,19 @@ cache:
     - _ccache/
 
 variables:
-  FEDORA_IMAGE: "registry.gitlab.gnome.org/gnome/glib/fedora:v20"
+  FEDORA_IMAGE: "registry.gitlab.gnome.org/gnome/glib/fedora:v26"
   COVERITY_IMAGE: "registry.gitlab.gnome.org/gnome/glib/coverity:v7"
-  DEBIAN_IMAGE: "registry.gitlab.gnome.org/gnome/glib/debian-stable:v14"
+  DEBIAN_IMAGE: "registry.gitlab.gnome.org/gnome/glib/debian-stable:v19"
-  MINGW_IMAGE: "registry.gitlab.gnome.org/gnome/glib/mingw:v10"
+  ALPINE_IMAGE: "registry.gitlab.gnome.org/gnome/glib/alpine:v3"
+  MINGW_IMAGE: "registry.gitlab.gnome.org/gnome/glib/mingw:v15"
   MESON_TEST_TIMEOUT_MULTIPLIER: 4
   G_MESSAGES_DEBUG: all
   MESON_COMMON_OPTIONS: "--buildtype debug --wrap-mode=nodownload --fatal-meson-warnings"
 
 # Default CI job setup; contrast with `.only-origin`.
 #
-# Don’t execute the pipeline when a merge request is merged into `main`, as it
+# Don’t execute the pipeline when a merge request is merged into `origin/main`,
-# will have already been tested
+# as it will have already been tested
 .only-default:
   only:
     - branches
@@ -30,7 +31,16 @@ variables:
     refs:
       - tags
     variables:
-      - $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+      - $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $CI_PROJECT_NAMESPACE == "GNOME"
+
+# As above, but does get executed on merge into `origin/main`. For use with
+# updating code coverage results and docs builds.
+.only-default-and-merges:
+  only:
+    - branches
+  except:
+    refs:
+      - tags
 
 # Some jobs run on CI runners which don’t have good isolation between CI jobs,
 # and don’t have much available resource. Limit those jobs to only ones on the
@@ -51,61 +61,123 @@ variables:
   except:
     - tags
 
+# Some jobs take a long time and are unlikely to find failures (or will find
+# failures which are not merge-blockers to fix), so they’re executed on a weekly
+# schedule in order to save CI resources and speed up branch pipelines.
+# But for specific merge requests, one may still want to run them, so make
+# possible to run them manually.
+.only-schedules-or-manual:
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+      when: never
+    # As per rule before, the following rules will only apply to non MR events
+    - if: $CI_PIPELINE_SOURCE == "schedule"
+      when: always
+    - if: $CI_PIPELINE_SOURCE != "schedule"
+      when: manual
+      allow_failure: true
+
+# Some jobs should be runnable only on schedules and when triggered by a branch
+# in the origin repository, but without
+.only-schedules-or-manual-in-default-branch:
+  rules:
+    - if: $CI_PROJECT_PATH != "GNOME/glib" || $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH
+      when: never
+    # As per rule before, the following rules will apply only to GNOME/glib:main
+    - if: $CI_PIPELINE_SOURCE == "schedule"
+      when: always
+    - if: $CI_PIPELINE_SOURCE != "schedule"
+      when: manual
+      allow_failure: true
+
+# Some jobs run on CI runners don’t have much available resource.
+# Limit those jobs to only ones on the origin repository (GNOME/glib),
+# rather than people’s forks or if ran manually.
+.only-origin-or-manual:
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+      when: never
+    - if: $CI_PIPELINE_SOURCE == "schedule"
+      when: never
+    - if: $CI_PROJECT_NAMESPACE == "GNOME"
+      when: always
+    - if: $CI_PROJECT_NAMESPACE != "GNOME"
+      when: manual
+      allow_failure: true
+
 .build-linux:
   before_script:
     - bash .gitlab-ci/show-execution-environment.sh
     - cp -r $HOME/subprojects/* subprojects/
 
 # FIXME: Work around https://gitlab.com/gitlab-org/gitlab/-/issues/391756
-.only-default-with-git:
+.with-git:
-  extends: .only-default
   before_script:
    - rm -rf subprojects/gvdb
+   - git config --global --add safe.directory "${PWD}"
    - git submodule update --init --depth 1
   variables:
     GIT_SUBMODULE_STRATEGY: "none"
     GIT_SUBMODULE_DEPTH: 1
 
 style-check-advisory:
-  extends: .only-default-with-git
+  extends:
+    - .only-default
+    - .with-git
   image: $DEBIAN_IMAGE
   stage: style-check
   allow_failure: true
   script:
-    - .gitlab-ci/run-style-check-diff.sh
+    - failed=
-    - .gitlab-ci/run-check-todos.sh
+    - .gitlab-ci/run-style-check-diff.sh || failed=1
+    - .gitlab-ci/run-check-todos.sh || failed=1
+    - test -z "$failed"
 
 sh-and-py-check:
-  extends: .only-default
+  extends:
+    - .only-default
+    - .with-git
   image: $DEBIAN_IMAGE
   stage: style-check
   allow_failure: false
   script:
-    - .gitlab-ci/run-shellcheck.sh
+    - failed=
-    - .gitlab-ci/run-black.sh
+    - tests/shellcheck.sh || failed=1
-    - .gitlab-ci/run-flake8.sh
+    - tests/black.sh || failed=1
+    - tests/flake8.sh || failed=1
+    - test -z "$failed"
+  variables:
+    LINT_WARNINGS_ARE_ERRORS: '1'
   only:
     changes:
       - "**/*.py"
       - "**/*.sh"
 
 style-check-mandatory:
-  extends: .only-default-with-git
+  extends:
+    - .only-default
+    - .with-git
   image: $DEBIAN_IMAGE
   stage: style-check
   allow_failure: false
   script:
-    - .gitlab-ci/run-reuse.sh
+    - tests/reuse.sh
+  variables:
+    LINT_WARNINGS_ARE_ERRORS: '1'
 
 fedora-x86_64:
   extends:
     - .build-linux
-    - .only-default
+    - .only-default-and-merges
+    - .with-git
   image: $FEDORA_IMAGE
   stage: build
   needs: []
   variables:
     CFLAGS: "-coverage -ftest-coverage -fprofile-arcs"
+  before_script:
+    - !reference [".build-linux", "before_script"]
+    - !reference [".with-git", "before_script"]
   script:
     - meson setup ${MESON_COMMON_OPTIONS}
             --werror
@@ -116,13 +188,25 @@ fedora-x86_64:
             -Dsystemtap=true
             -Ddtrace=true
             -Dinstalled_tests=true
-            -Dgtk_doc=true
+            -Ddocumentation=true
+            -Dintrospection=enabled
+            -Dman-pages=enabled
             _build
     - meson compile -C _build
     - mkdir -p _coverage
     - lcov --config-file .lcovrc --directory _build --capture --initial --output-file "_coverage/${CI_JOB_NAME}-baseline.lcov"
     - .gitlab-ci/run-tests.sh
     - lcov --config-file .lcovrc --directory _build --capture --output-file "_coverage/${CI_JOB_NAME}.lcov"
+    # Copy the built documentation to an artifact directory. The build for docs.gtk.org
+    # can then pull it from there — see https://gitlab.gnome.org/GNOME/gtk/-/blob/docs-gtk-org/README.md
+    - mkdir -p _reference/
+    - mv _build/docs/reference/glib/glib/ _reference/glib/
+    - mv _build/docs/reference/glib/glib-unix/ _reference/glib-unix/
+    - mv _build/docs/reference/gmodule/gmodule/ _reference/gmodule/
+    - mv _build/docs/reference/gobject/gobject/ _reference/gobject/
+    - mv _build/docs/reference/gio/gio/ _reference/gio/
+    - mv _build/docs/reference/gio/gio-unix/ _reference/gio-unix/
+    - mv _build/docs/reference/girepository/girepository/ _reference/girepository/
   artifacts:
     reports:
       junit:
@@ -135,24 +219,20 @@ fedora-x86_64:
       - "_build/config.h"
       - "_build/glib/glibconfig.h"
       - "_build/meson-logs"
-      - "_build/docs/reference/glib/glib-undeclared.txt"
-      - "_build/docs/reference/glib/glib-undocumented.txt"
-      - "_build/docs/reference/glib/glib-unused.txt"
-      - "_build/docs/reference/gobject/gobject-undeclared.txt"
-      - "_build/docs/reference/gobject/gobject-undocumented.txt"
-      - "_build/docs/reference/gobject/gobject-unused.txt"
-      - "_build/docs/reference/gio/gio-undeclared.txt"
-      - "_build/docs/reference/gio/gio-undocumented.txt"
-      - "_build/docs/reference/gio/gio-unused.txt"
       - "_coverage"
+      - "_reference"
 
 debian-stable-x86_64:
   extends:
     - .build-linux
     - .only-default
+    - .with-git
   image: $DEBIAN_IMAGE
   stage: build
   needs: []
+  before_script:
+    - !reference [".build-linux", "before_script"]
+    - !reference [".with-git", "before_script"]
   script:
     - meson setup ${MESON_COMMON_OPTIONS}
             --werror
@@ -178,10 +258,81 @@ debian-stable-x86_64:
       - "_build/glib/glibconfig.h"
       - "_build/meson-logs"
 
+hurd-i386:
+  extends:
+    - .only-schedules-or-manual
+    - .with-git
+  stage: build
+  tags:
+    - hurd
+  needs: []
+  script:
+    # FIXME: We can’t use ${MESON_COMMON_OPTIONS} here because the Hurd runner
+    # has Meson 1.3 installed. See the comment below about the same problem on
+    # FreeBSD.
+    - meson setup
+            --buildtype debug
+            --wrap-mode=nodownload
+            --werror
+            --default-library=both
+            --prefix=$HOME/glib-installed
+            --localstatedir=/var
+            --libdir=lib
+            _build
+    - meson compile -C _build
+    - .gitlab-ci/run-tests.sh
+  artifacts:
+    reports:
+      junit:
+        - _build/meson-logs/testlog.junit.xml
+        - _build/meson-logs/testlog-*.junit.xml
+    name: "glib-${CI_JOB_NAME}-${CI_COMMIT_REF_NAME}"
+    when: always
+    expire_in: 1 week
+    paths:
+      - "_build/config.h"
+      - "_build/glib/glibconfig.h"
+      - "_build/meson-logs"
+
+muslc-alpine-x86_64:
+  extends:
+    - .build-linux
+    - .only-schedules-or-manual
+    - .with-git
+  image: $ALPINE_IMAGE
+  stage: build
+  needs: []
+  before_script:
+    - !reference [".build-linux", "before_script"]
+    - !reference [".with-git", "before_script"]
+  script:
+    - meson setup ${MESON_COMMON_OPTIONS}
+            --werror
+            --default-library=both
+            --prefix=$HOME/glib-installed
+            --localstatedir=/var
+            --libdir=lib
+            -Dsystemtap=true
+            _build
+    - meson compile -C _build
+    - .gitlab-ci/run-tests.sh
+  artifacts:
+    reports:
+      junit:
+        - _build/meson-logs/testlog.junit.xml
+        - _build/meson-logs/testlog-*.junit.xml
+    name: "glib-${CI_JOB_NAME}-${CI_COMMIT_REF_NAME}"
+    when: always
+    expire_in: 1 week
+    paths:
+      - "_build/config.h"
+      - "_build/glib/glibconfig.h"
+      - "_build/meson-logs"
+
 installed-tests:
   extends:
     - .build-linux
-    - .only-schedules
+    - .only-schedules-or-manual
   image: $FEDORA_IMAGE
   stage: build
   needs: []
@@ -219,10 +370,16 @@ installed-tests:
 G_DISABLE_ASSERT:
   extends:
     - .build-linux
-    - .only-schedules
+    - .only-schedules-or-manual
+    - .with-git
   image: $FEDORA_IMAGE
   stage: build
   needs: []
+  variables:
+    MESON_TEST_TIMEOUT_MULTIPLIER: 15
+  before_script:
+    - !reference [".build-linux", "before_script"]
+    - !reference [".with-git", "before_script"]
   script:
     - meson setup ${MESON_COMMON_OPTIONS}
             --werror
@@ -230,9 +387,11 @@ G_DISABLE_ASSERT:
             -Ddtrace=true
             -Dinstalled_tests=true
             -Dglib_assert=false
+            -Dintrospection=enabled
             _build
     - meson compile -C _build
-    - bash -x ./.gitlab-ci/run-tests.sh
+    # Also take the opportunity to run the thorough tests (which are slow)
+    - bash -x ./.gitlab-ci/run-tests.sh --setup thorough
   artifacts:
     reports:
       junit:
@@ -249,18 +408,23 @@ G_DISABLE_ASSERT:
 valgrind:
   extends:
     - .build-linux
-    - .only-schedules
+    - .only-schedules-or-manual
+    - .with-git
   image: $FEDORA_IMAGE
   stage: analysis
   needs: []
   variables:
     MESON_TEST_TIMEOUT_MULTIPLIER: 15
+  before_script:
+    - !reference [".build-linux", "before_script"]
+    - !reference [".with-git", "before_script"]
   script:
     - meson setup ${MESON_COMMON_OPTIONS}
             --werror
             -Dsystemtap=true
             -Ddtrace=true
             -Dinstalled_tests=true
+            -Dintrospection=enabled
             _build
     - meson compile -C _build
     # Valgrind doesn’t work when the soft FD limit is set too high
@@ -329,7 +493,7 @@ cross-mingw64:
       - _build/gobject/libgobject-2.0-0.dll
 
 msys2-mingw32:
-  extends: .only-default
+  extends: .only-default-and-merges
   stage: build
   tags:
     - win32-ps
@@ -339,10 +503,6 @@ msys2-mingw32:
     CHERE_INVOKING: "yes"
     CFLAGS: -coverage -ftest-coverage -fprofile-arcs
     PYTHONUTF8: "1"
-    # FIXME: For some reason enabling jit debugging "fixes" random python crashes
-    # see https://github.com/msys2/MINGW-packages/issues/11864 and
-    # https://gitlab.gnome.org/GNOME/glib/-/merge_requests/3280#note_1678973
-    MSYS: "winjitdebug"
   script:
     - C:\msys64\usr\bin\pacman --noconfirm -Syyuu --ask 20
     - C:\msys64\usr\bin\bash .gitlab-ci/show-execution-environment.sh
@@ -358,9 +518,10 @@ msys2-mingw32:
     paths:
       - _build/meson-logs
       - _coverage/
+      - _reference/
 
 msys2-clang64:
-  extends: .only-schedules
+  extends: .only-schedules-or-manual
   stage: build
   tags:
     - win32-ps
@@ -369,10 +530,6 @@ msys2-clang64:
     MSYSTEM: "CLANG64"
     CHERE_INVOKING: "yes"
     PYTHONUTF8: "1"
-    # FIXME: For some reason enabling jit debugging "fixes" random python crashes
-    # see https://github.com/msys2/MINGW-packages/issues/11864 and
-    # https://gitlab.gnome.org/GNOME/glib/-/merge_requests/3280#note_1678973
-    MSYS: "winjitdebug"
   script:
     - C:\msys64\usr\bin\pacman --noconfirm -Syyuu --ask 20
     - C:\msys64\usr\bin\bash .gitlab-ci/show-execution-environment.sh
@@ -444,54 +601,8 @@ vs2017-x64-static:
     paths:
       - _build/meson-logs
 
-freebsd-12-x86_64:
-  # The FreeBSD 13 build is run on each commit, so the FreeBSD 12 build can be
-  # run less regularly to save CI resources. The chance of a regression on
-  # FreeBSD 12 and not FreeBSD 13 is tiny.
-  extends: .only-schedules
-  stage: build
-  tags:
-    # To run a FreeBSD builder, install gitlab-runner package and start both
-    # gitlab-runner and dbus service because we need /var/lib/dbus/machine-id.
-    # To compile GLib, you still have to install the following packages:
-    # desktop-file-utils gettext libiconv meson pkgconf python3 shared-mime-info
-    - freebsd-12
-  needs: []
-  variables:
-    # CPPFLAGS is required because libintl doesn't use pkg-config.
-    CPPFLAGS: -I/usr/local/include
-    # FIXME: Workaround meson inability to set LD_LIBRARY_PATH.
-    # https://github.com/mesonbuild/meson/issues/1383
-    # https://github.com/mesonbuild/meson/issues/1635
-    # https://github.com/mesonbuild/meson/issues/2881
-    LDFLAGS: -L/usr/local/lib -Wl,--disable-new-dtags
-    # FreeBSD supports C.UTF-8 locale since 12.1.
-    LANG: C.UTF-8
-  before_script:
-    - bash .gitlab-ci/show-execution-environment.sh
-  script:
-    # We cannot use -Wl,--no-undefined because GLib uses 'environ' variable.
-    # FreeBSD supports xattr, but its API is different from Linux xattr.
-    # FIXME: extattr(2) support: https://gitlab.gnome.org/GNOME/glib/issues/1404
-    # localstatedir is needed for access to /var/lib/dbus/machine-id
-    - meson setup ${MESON_COMMON_OPTIONS} --localstatedir=/var -Db_lundef=false -Dxattr=false _build
-    - meson compile -C _build
-    - bash -x ./.gitlab-ci/run-tests.sh
-  artifacts:
-    reports:
-      junit:
-        - _build/meson-logs/testlog.junit.xml
-        - _build/meson-logs/testlog-*.junit.xml
-    name: "glib-${CI_JOB_NAME}-${CI_COMMIT_REF_NAME}"
-    when: always
-    expire_in: 1 week
-    paths:
-      - "_build/config.h"
-      - "_build/glib/glibconfig.h"
-      - "_build/meson-logs"
-
 freebsd-13-x86_64:
-  extends: .only-origin
+  extends: .only-origin-or-manual
   stage: build
   tags:
     - freebsd-13
@@ -503,7 +614,14 @@ freebsd-13-x86_64:
   before_script:
     - bash .gitlab-ci/show-execution-environment.sh
   script:
-    - meson setup ${MESON_COMMON_OPTIONS} --localstatedir=/var -Db_lundef=false -Dxattr=false _build
+    # FIXME: We can’t use ${MESON_COMMON_OPTIONS} here because the FreeBSD 13
+    # runner has Meson 1.3 installed. This has an API hole where previous
+    # methods of getting paths from files() objects are rejected as deprecated,
+    # but no replacements are available. Hence, we can’t build with
+    # --fatal-meson-warnings. This should be fixed in Meson 1.4. It’s also fine
+    # with Meson 1.2.3 (which is what we use on all the other CI runners).
+    # See https://github.com/GNOME/glib/commit/71061fdcb33b8c26f5f8467cb3ac10704d65c87d
+    - meson setup --buildtype debug --wrap-mode=nodownload --localstatedir=/var -Db_lundef=false -Dxattr=false _build
     - meson compile -C _build
     - bash -x ./.gitlab-ci/run-tests.sh
   artifacts:
@@ -520,6 +638,7 @@ freebsd-13-x86_64:
       - "_build/meson-logs"
 
 macos-x86_64:
+  # The macOS runner is not allowed in forks. This is about trust, not capacity.
   extends: .only-origin
   stage: build
   tags:
@@ -549,8 +668,9 @@ macos-x86_64:
     - ln -s /opt/cmake/CMake.app/Contents/bin/cmake .venv/bin
     - ln -s /opt/ccache/ccache .venv/bin
     - source .venv/bin/activate
-    - pip3 install meson==1.2.0
+    - pip3 install meson==1.2.3
     - pip3 install ninja==1.11.1
+    - pip3 install packaging==23.2
   script:
     # FIXME: Use --wrap-mode=default so we download dependencies each time,
     # until the macOS runner is a VM where we can use a pre-made image which
@@ -601,7 +721,7 @@ coverage:
 scan-build:
   extends:
     - .build-linux
-    - .only-schedules
+    - .only-schedules-or-manual
   image: $FEDORA_IMAGE
   stage: analysis
   needs: []
@@ -615,6 +735,7 @@ scan-build:
             -Dsystemtap=true
             -Ddtrace=true
             -Dinstalled_tests=true
+            -Dintrospection=enabled
             _scan_build
     - ninja -C _scan_build scan-build
   artifacts:
@@ -627,7 +748,7 @@ scan-build:
 .coverity:
   extends:
     - .build-linux
-    - .only-schedules
+    - .only-schedules-or-manual-in-default-branch
   image: $COVERITY_IMAGE
   stage: analysis
   needs: []
@@ -644,6 +765,7 @@ scan-build:
             -Dsystemtap=true
             -Ddtrace=true
             -Dinstalled_tests=true
+            -Dintrospection=enabled
             _coverity_build
     - $HOME/cov-analysis-linux64-*/bin/cov-build --dir cov-int meson compile -C _coverity_build
     - tar cfz cov-int.tar.gz cov-int
@@ -679,17 +801,22 @@ dist-job:
     - git submodule update --init
     - for m in $(git submodule foreach -q 'echo $path'); do git config --global --add safe.directory "${PWD}/${m}"; done
     - meson subprojects download
-    - meson setup ${MESON_COMMON_OPTIONS} --buildtype release -Dgtk_doc=true -Dman=true _build
+    - meson setup ${MESON_COMMON_OPTIONS} --buildtype release -Ddocumentation=true -Dman-pages=enabled _build
     - meson dist -C _build
-    - ninja -C _build glib-doc gobject-doc gio-doc
+    # Compile again to build the docs
-    - tar -c -J -f "glib-docs-$CI_COMMIT_TAG.tar.xz" -C docs/reference/glib html
+    - meson compile -C _build
-    - tar -c -J -f "gobject-docs-$CI_COMMIT_TAG.tar.xz" -C docs/reference/gobject html
+    - tar -c -J -f "glib-docs-$CI_COMMIT_TAG.tar.xz" -C _build/docs/reference/glib glib
-    - tar -c -J -f "gio-docs-$CI_COMMIT_TAG.tar.xz" -C docs/reference/gio html
+    - tar -c -J -f "gmodule-docs-$CI_COMMIT_TAG.tar.xz" -C _build/docs/reference/gmodule gmodule
+    - tar -c -J -f "gobject-docs-$CI_COMMIT_TAG.tar.xz" -C _build/docs/reference/gobject gobject
+    - tar -c -J -f "gio-docs-$CI_COMMIT_TAG.tar.xz" -C _build/docs/reference/gio gio
+    - tar -c -J -f "girepository-docs-$CI_COMMIT_TAG.tar.xz" -C _build/docs/reference/girepository girepository
   artifacts:
     paths:
       - "${CI_PROJECT_DIR}/_build/glib-docs-$CI_COMMIT_TAG.tar.xz"
+      - "${CI_PROJECT_DIR}/_build/gmodule-docs-$CI_COMMIT_TAG.tar.xz"
       - "${CI_PROJECT_DIR}/_build/gobject-docs-$CI_COMMIT_TAG.tar.xz"
       - "${CI_PROJECT_DIR}/_build/gio-docs-$CI_COMMIT_TAG.tar.xz"
+      - "${CI_PROJECT_DIR}/_build/girepository-docs-$CI_COMMIT_TAG.tar.xz"
       - "${CI_PROJECT_DIR}/_build/meson-dist/glib-*.tar.xz"
 
 issue-bot:

.gitlab-ci/alpine.Dockerfile

@@ -0,0 +1,38 @@
+FROM alpine:3.19
+
+RUN apk add --no-cache \
+    bash \
+    build-base \
+    bzip2-dev \
+    dbus \
+    desktop-file-utils \
+    docbook-xml \
+    docbook-xsl \
+    gettext-dev \
+    git \
+    libffi-dev \
+    libxml2-utils \
+    libxslt \
+    meson \
+    musl-locales \
+    py3-pip \
+    python3 \
+    pcre2-dev \
+    shared-mime-info \
+    tzdata \
+    util-linux-dev \
+    zlib-dev
+
+ENV LANG=C.UTF-8 LANGUAGE=C.UTF-8 LC_ALL=C.UTF-8 MUSL_LOCPATH=/usr/share/i18n/locales/musl
+
+RUN pip3 install --break-system-packages meson==1.2.3
+
+ARG HOST_USER_ID=5555
+ENV HOST_USER_ID ${HOST_USER_ID}
+RUN adduser -D -u $HOST_USER_ID -s /bin/bash user
+
+USER user
+WORKDIR /home/user
+
+COPY cache-subprojects.sh .
+RUN ./cache-subprojects.sh

.gitlab-ci/check-missing-install-tag.py

@@ -1,31 +0,0 @@
-#!/usr/bin/env python3
-
-"""
-This script checks Meson configuration logs to verify no installed file is
-missing installation tag.
-"""
-
-import argparse
-import json
-from pathlib import Path
-
-
-def main():
-    parser = argparse.ArgumentParser()
-    parser.add_argument("builddir", type=Path)
-    args = parser.parse_args()
-
-    success = True
-    path = args.builddir / "meson-info" / "intro-install_plan.json"
-    with path.open(encoding="utf-8") as f:
-        install_plan = json.load(f)
-        for target in install_plan.values():
-            for info in target.values():
-                if not info["tag"]:
-                    print("Missing install_tag for", info["destination"])
-                    success = False
-    return 0 if success else 1
-
-
-if __name__ == "__main__":
-    exit(main())

.gitlab-ci/debian-stable.Dockerfile

@@ -1,4 +1,4 @@
-FROM debian:bullseye
+FROM debian:bookworm
 
 RUN apt-get update -qq && apt-get install --no-install-recommends -qq -y \
     bindfs \
@@ -16,8 +16,10 @@ RUN apt-get update -qq && apt-get install --no-install-recommends -qq -y \
     gdb \
     g++ \
     gettext \
+    gi-docgen \
     git \
     libc6-dev \
+    gobject-introspection \
     gtk-doc-tools \
     itstool \
     lcov \
@@ -25,6 +27,7 @@ RUN apt-get update -qq && apt-get install --no-install-recommends -qq -y \
     libdbus-1-dev \
     libelf-dev \
     libffi-dev \
+    libgirepository1.0-dev \
     libmount-dev \
     libpcre2-dev \
     libselinux1-dev \
@@ -34,9 +37,11 @@ RUN apt-get update -qq && apt-get install --no-install-recommends -qq -y \
     locales \
     ninja-build \
     python3 \
+    python3-packaging \
     python3-pip \
     python3-setuptools \
     python3-wheel \
+    reuse \
     shared-mime-info \
     shellcheck \
     systemtap-sdt-dev \
@@ -62,14 +67,12 @@ RUN locale-gen de_DE.UTF-8 \
  && locale-gen lt_LT.UTF-8 \
  && locale-gen pl_PL.UTF-8 \
  && locale-gen ru_RU.UTF-8 \
+ && locale-gen th_TH.UTF-8 \
  && locale-gen tr_TR.UTF-8
 
 ENV LANG=C.UTF-8 LANGUAGE=C.UTF-8 LC_ALL=C.UTF-8
 
-RUN pip3 install meson==0.60.3
+RUN pip3 install --break-system-packages meson==1.2.3
-
-# FIXME: Once we use Debian Bookworm, we can just install the `reuse` package
-RUN pip3 install reuse==1.0.0
 
 ARG HOST_USER_ID=5555
 ENV HOST_USER_ID ${HOST_USER_ID}

.gitlab-ci/fedora.Dockerfile

@@ -1,4 +1,4 @@
-FROM fedora:34
+FROM fedora:37
 
 RUN dnf -y update \
  && dnf -y install \
@@ -15,24 +15,28 @@ RUN dnf -y update \
     gcc-c++ \
     gdb \
     gettext \
+    gi-docgen \
     git \
     glibc-devel \
+    glibc-gconv-extra \
     glibc-headers \
     glibc-langpack-de \
     glibc-langpack-el \
-    glibc-langpack-el \
     glibc-langpack-en \
     glibc-langpack-es \
-    glibc-langpack-es \
     glibc-langpack-fa \
     glibc-langpack-fr \
+    glibc-langpack-gu \
     glibc-langpack-hr \
     glibc-langpack-ja \
     glibc-langpack-lt \
     glibc-langpack-pl \
     glibc-langpack-ru \
+    glibc-langpack-th \
     glibc-langpack-tr \
     "gnome-desktop-testing >= 2018.1" \
+    gobject-introspection \
+    gobject-introspection-devel \
     gtk-doc \
     itstool \
     lcov \
@@ -45,6 +49,8 @@ RUN dnf -y update \
     ninja-build \
     pcre2-devel \
     "python3-dbusmock >= 0.18.3-2" \
+    python3-docutils \
+    python3-packaging \
     python3-pip \
     python3-pygments \
     python3-wheel \
@@ -74,7 +80,7 @@ RUN dnf -y update \
     make \
  && dnf clean all
 
-RUN pip3 install meson==0.60.3
+RUN pip3 install meson==1.2.3
 
 COPY install-gitlab-cobertura-tools.sh .
 RUN ./install-gitlab-cobertura-tools.sh

.gitlab-ci/mingw.Dockerfile

@@ -1,72 +1,17 @@
-FROM fedora:34
+FROM registry.gitlab.gnome.org/gnome/glib/fedora:v25
+
+USER root
 
 RUN dnf -y install \
-    bindfs \
-    clang \
-    clang-analyzer \
-    desktop-file-utils \
-    elfutils-libelf-devel \
-    findutils \
-    fuse \
-    gcc \
-    gcc-c++ \
-    gettext \
-    git \
-    glibc-devel \
-    glibc-headers \
-    glibc-langpack-de \
-    glibc-langpack-el \
-    glibc-langpack-el \
-    glibc-langpack-en \
-    glibc-langpack-es \
-    glibc-langpack-es \
-    glibc-langpack-fa \
-    glibc-langpack-fr \
-    glibc-langpack-hr \
-    glibc-langpack-ja \
-    glibc-langpack-lt \
-    glibc-langpack-pl \
-    glibc-langpack-ru \
-    glibc-langpack-tr \
-    gtk-doc \
-    itstool \
-    lcov \
-    libattr-devel \
-    libffi-devel \
-    libmount-devel \
-    libselinux-devel \
-    libxslt \
     mingw64-gcc \
     mingw64-gcc-c++ \
     mingw64-gettext \
     mingw64-libffi \
     mingw64-zlib \
-    ncurses-compat-libs \
-    ninja-build \
-    pcre2-devel \
-    python3 \
-    python3-pip \
-    python3-wheel \
-    systemtap-sdt-devel \
-    unzip \
-    wget \
-    xz \
-    zlib-devel \
  && dnf clean all
 
 WORKDIR /opt
 COPY cross_file_mingw64.txt /opt
 
-RUN pip3 install meson==0.60.3
-
-ARG HOST_USER_ID=5555
-ENV HOST_USER_ID ${HOST_USER_ID}
-RUN useradd -u $HOST_USER_ID -ms /bin/bash user
-
 USER user
-WORKDIR /home/user
+WORKDIR /home/user
-
-COPY cache-subprojects.sh .
-RUN ./cache-subprojects.sh
-
-ENV LANG C.UTF-8

.gitlab-ci/run-black.sh

@@ -1,6 +0,0 @@
-#!/bin/bash
-
-set -e
-
-# shellcheck disable=SC2046
-black --diff --check $(git ls-files '*.py')

.gitlab-ci/run-flake8.sh

@@ -1,9 +0,0 @@
-#!/bin/bash
-
-set -e
-
-# Disable formatting warnings in flake8, as we use `black` to handle that.
-formatting_warnings=E101,E111,E114,E115,E116,E117,E12,E13,E2,E3,E401,E5,E70,W1,W2,W3,W5
-
-# shellcheck disable=SC2046
-flake8 --max-line-length=88 --ignore="$formatting_warnings" $(git ls-files '*.py')

.gitlab-ci/run-shellcheck.sh

@@ -1,7 +0,0 @@
-#!/bin/bash
-
-set -e
-
-# Ignoring third-party directories that we don't want to parse
-# shellcheck disable=SC2046
-shellcheck $(git ls-files '*.sh' | grep -Ev "glib/libcharset|glib/dirent")

.gitlab-ci/run-style-check-diff.sh

@@ -2,17 +2,15 @@
 
 set -e
 
-ancestor_horizon=28  # days (4 weeks)
-
 # Wrap everything in a subshell so we can propagate the exit status.
+exit_status=0
 (
 
 source .gitlab-ci/search-common-ancestor.sh
 
-git diff -U0 --no-color "${newest_common_ancestor_sha}" | .gitlab-ci/clang-format-diff.py -binary "clang-format-11" -p1
+git diff -U0 --no-color "${newest_common_ancestor_sha}" | .gitlab-ci/clang-format-diff.py -binary "clang-format-14" -p1
 
-)
+) || exit_status=$?
-exit_status=$?
 
 # The style check is not infallible. The clang-format configuration cannot
 # perfectly describe GLib’s coding style: in particular, it cannot align

.gitlab-ci/run-tests.sh

@@ -2,8 +2,6 @@
 
 set -ex
 
-./.gitlab-ci/check-missing-install-tag.py _build
-
 meson test -v \
         -C _build \
         --timeout-multiplier "${MESON_TEST_TIMEOUT_MULTIPLIER}" \

.gitlab-ci/test-msvc.bat

@@ -12,25 +12,15 @@ for %%x in (%*) do (
 set args=%args:~1%
 
 :: FIXME: make warnings fatal
-pip3 install --upgrade --user meson==1.0.0  || goto :error
+pip3 install --upgrade --user meson==1.2.3 packaging==23.2  || goto :error
 meson setup %args% _build || goto :error
-python .gitlab-ci/check-missing-install-tag.py _build || goto :error
 meson compile -C _build || goto :error
 
 meson test -v -C _build --timeout-multiplier %MESON_TEST_TIMEOUT_MULTIPLIER% || goto :error
 meson test -v -C _build --timeout-multiplier %MESON_TEST_TIMEOUT_MULTIPLIER% --setup=unstable_tests --suite=failing --suite=flaky
 
-:: Workaround meson issue https://github.com/mesonbuild/meson/issues/9894
-python -c "n = '_build/meson-logs/testlog.junit.xml'; c = open(n, 'rb').read().replace(b'\x1b', b''); open(n, 'wb').write(c)" || goto :error
-python -c "n = '_build/meson-logs/testlog-unstable_tests.junit.xml'; c = open(n, 'rb').read().replace(b'\x1b', b''); open(n, 'wb').write(c)"
-
 :: FIXME: can we get code coverage support?
 
 goto :EOF
 :error
-
-:: Workaround meson issue https://github.com/mesonbuild/meson/issues/9894
-python -c "n = '_build/meson-logs/testlog.junit.xml'; c = open(n, 'rb').read().replace(b'\x1b', b''); open(n, 'wb').write(c)"
-python -c "n = '_build/meson-logs/testlog-unstable_tests.junit.xml'; c = open(n, 'rb').read().replace(b'\x1b', b''); open(n, 'wb').write(c)"
-
 exit /b 1

.gitlab-ci/test-msys2.sh

@@ -11,10 +11,13 @@ pacman --noconfirm -S --needed \
     lcov \
     "${MINGW_PACKAGE_PREFIX}"-ccache \
     "${MINGW_PACKAGE_PREFIX}"-gettext \
+    "${MINGW_PACKAGE_PREFIX}"-gi-docgen \
+    "${MINGW_PACKAGE_PREFIX}"-gobject-introspection \
     "${MINGW_PACKAGE_PREFIX}"-libffi \
     "${MINGW_PACKAGE_PREFIX}"-meson \
     "${MINGW_PACKAGE_PREFIX}"-pcre2 \
     "${MINGW_PACKAGE_PREFIX}"-python3 \
+    "${MINGW_PACKAGE_PREFIX}"-python-docutils \
     "${MINGW_PACKAGE_PREFIX}"-python-pip \
     "${MINGW_PACKAGE_PREFIX}"-toolchain \
     "${MINGW_PACKAGE_PREFIX}"-zlib \
@@ -26,20 +29,24 @@ CCACHE_BASEDIR="$(pwd)"
 CCACHE_DIR="${CCACHE_BASEDIR}/_ccache"
 export CCACHE_BASEDIR CCACHE_DIR
 
-pip3 install --upgrade --user meson==1.0.0
+pip3 install --upgrade --user packaging==23.2
 
 PATH="$(cygpath "$USERPROFILE")/.local/bin:$HOME/.local/bin:$PATH"
 DIR="$(pwd)"
 export PATH CFLAGS
 
-if [[ "$MSYSTEM" == "CLANG64" ]]; then
+# FIXME: We can’t use ${MESON_COMMON_OPTIONS} here because this script installs
-    # FIXME: fix the clang build warnings
+# Meson 1.3. See the comment in .gitlab-ci.yml about the same problem on
-    # shellcheck disable=SC2086
+# FreeBSD.
-    meson setup ${MESON_COMMON_OPTIONS} _build
+# shellcheck disable=SC2086
-else
+meson setup \
-    # shellcheck disable=SC2086
+    --buildtype=debug \
-    meson setup ${MESON_COMMON_OPTIONS} --werror _build
+    --wrap-mode=nodownload \
-fi
+    --werror \
+    -Ddocumentation=true \
+    -Dintrospection=enabled \
+    -Dman-pages=enabled \
+    _build
 
 meson compile -C _build
 
@@ -65,3 +72,9 @@ if [[ "$CFLAGS" == *"-coverage"* ]]; then
         --capture \
         --output-file "${DIR}/_coverage/${CI_JOB_NAME}.lcov"
 fi
+
+# Copy the built documentation to an artifact directory. The build for docs.gtk.org
+# can then pull it from there — see https://gitlab.gnome.org/GNOME/gtk/-/blob/docs-gtk-org/README.md
+mkdir -p _reference/
+mv _build/docs/reference/glib/glib-win32/ _reference/glib-win32/
+mv _build/docs/reference/gio/gio-win32/ _reference/gio-win32/

.gitlab-ci/thorough-test-wrapper.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+#
+# Copyright 2024 GNOME Foundation, Inc.
+#
+# SPDX-License-Identifier: LGPL-2.1-or-later
+#
+# Original author: Philip Withnall
+
+set -e
+
+# If the test is run under Python (e.g. the first argument to this script is
+# /usr/bin/python3) or if it’s the special xmllint test in GLib, then don’t
+# pass the GTest `-m thorough` argument to it.
+if [[ "$1" == *"python"* ||
+      "$1" == *"xmllint" ]]; then
+  args=()
+else
+  # See the documentation for g_test_init()
+  args=("-m" "thorough")
+fi
+
+exec "$@" "${args[@]}"

.lcovrc

@@ -1,13 +1,16 @@
 # lcov and genhtml configuration
-# See http://ltp.sourceforge.net/coverage/lcov/lcovrc.5.php
+# See lcovrc(5)
 
 # Always enable branch coverage
 lcov_branch_coverage = 1
 
 # Exclude precondition assertions, as we can never reasonably get full branch
 # coverage of them, as they should never normally fail.
+# Similarly exclude g_clear_*() functions (such as g_clear_object(),
+# g_clear_pointer(), etc.) as it’s not useful to test both sides of the branch
+# in them.
 # See https://github.com/linux-test-project/lcov/issues/44
-lcov_excl_br_line = LCOV_EXCL_BR_LINE|g_return_if_fail|g_return_val_if_fail|g_assert|g_assert_
+lcov_excl_br_line = LCOV_EXCL_BR_LINE|g_return_if_fail|g_return_val_if_fail|g_assert|g_assert_|g_clear_
 
 # Similarly for unreachable assertions.
 lcov_excl_line = LCOV_EXCL_LINE|g_return_if_reached|g_return_val_if_reached|g_assert_not_reached

.reuse/dep5

@@ -41,3 +41,22 @@ License: CC0-1.0
 Files: docs/reference/glib/gvariant-*.svg
 Copyright: 2022 Philip Withnall
 License: CC-BY-SA-3.0
+
+# libgirepository uses cmph as a copylib. Adding copyright/license data to the
+# files there would cause divergence from upstream. See
+# girepository/cmph/README-CMPH-IMPORT.txt.
+Files: girepository/cmph/*
+Copyright: CMPH contributors
+License: LGPL-2.1-only or MPL-1.1
+
+# gnulib is a copylib. Adding copyright/license data to the files there would
+# cause divergence from upstream. See glib/gnulib/README.
+Files: glib/gnulib/*
+Copyright: gnulib contributors
+License: LGPL-2.1-or-later
+
+# libcharset is a copylib. Adding copyright/license data to the files there
+# would cause divergence from upstream. See glib/libcharset/README.
+Files: glib/libcharset/*
+Copyright: libcharset contributors
+License: LGPL-2.1-or-later

LICENSES/LGPL-2.1-only.txt

@@ -0,0 +1,175 @@
+GNU LESSER GENERAL PUBLIC LICENSE
+
+Version 2.1, February 1999
+
+Copyright (C) 1991, 1999 Free Software Foundation, Inc.
+51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+
+Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
+
+[This is the first released version of the Lesser GPL.  It also counts as the successor of the GNU Library Public License, version 2, hence the version number 2.1.]
+
+Preamble
+
+The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public Licenses are intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users.
+
+This license, the Lesser General Public License, applies to some specially designated software packages--typically libraries--of the Free Software Foundation and other authors who decide to use it. You can use it too, but we suggest you first think carefully about whether this license or the ordinary General Public License is the better strategy to use in any particular case, based on the explanations below.
+
+When we speak of free software, we are referring to freedom of use, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish); that you receive source code or can get it if you want it; that you can change the software and use pieces of it in new free programs; and that you are informed that you can do these things.
+
+To protect your rights, we need to make restrictions that forbid distributors to deny you these rights or to ask you to surrender these rights. These restrictions translate to certain responsibilities for you if you distribute copies of the library or if you modify it.
+
+For example, if you distribute copies of the library, whether gratis or for a fee, you must give the recipients all the rights that we gave you. You must make sure that they, too, receive or can get the source code. If you link other code with the library, you must provide complete object files to the recipients, so that they can relink them with the library after making changes to the library and recompiling it. And you must show them these terms so they know their rights.
+
+We protect your rights with a two-step method: (1) we copyright the library, and (2) we offer you this license, which gives you legal permission to copy, distribute and/or modify the library.
+
+To protect each distributor, we want to make it very clear that there is no warranty for the free library. Also, if the library is modified by someone else and passed on, the recipients should know that what they have is not the original version, so that the original author's reputation will not be affected by problems that might be introduced by others.
+
+Finally, software patents pose a constant threat to the existence of any free program. We wish to make sure that a company cannot effectively restrict the users of a free program by obtaining a restrictive license from a patent holder. Therefore, we insist that any patent license obtained for a version of the library must be consistent with the full freedom of use specified in this license.
+
+Most GNU software, including some libraries, is covered by the ordinary GNU General Public License. This license, the GNU Lesser General Public License, applies to certain designated libraries, and is quite different from the ordinary General Public License. We use this license for certain libraries in order to permit linking those libraries into non-free programs.
+
+When a program is linked with a library, whether statically or using a shared library, the combination of the two is legally speaking a combined work, a derivative of the original library. The ordinary General Public License therefore permits such linking only if the entire combination fits its criteria of freedom. The Lesser General Public License permits more lax criteria for linking other code with the library.
+
+We call this license the "Lesser" General Public License because it does Less to protect the user's freedom than the ordinary General Public License. It also provides other free software developers Less of an advantage over competing non-free programs. These disadvantages are the reason we use the ordinary General Public License for many libraries. However, the Lesser license provides advantages in certain special circumstances.
+
+For example, on rare occasions, there may be a special need to encourage the widest possible use of a certain library, so that it becomes a de-facto standard. To achieve this, non-free programs must be allowed to use the library. A more frequent case is that a free library does the same job as widely used non-free libraries. In this case, there is little to gain by limiting the free library to free software only, so we use the Lesser General Public License.
+
+In other cases, permission to use a particular library in non-free programs enables a greater number of people to use a large body of free software. For example, permission to use the GNU C Library in non-free programs enables many more people to use the whole GNU operating system, as well as its variant, the GNU/Linux operating system.
+
+Although the Lesser General Public License is Less protective of the users' freedom, it does ensure that the user of a program that is linked with the Library has the freedom and the wherewithal to run that program using a modified version of the Library.
+
+The precise terms and conditions for copying, distribution and modification follow. Pay close attention to the difference between a "work based on the library" and a "work that uses the library". The former contains code derived from the library, whereas the latter must be combined with the library in order to run.
+
+TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+0. This License Agreement applies to any software library or other program which contains a notice placed by the copyright holder or other authorized party saying it may be distributed under the terms of this Lesser General Public License (also called "this License"). Each licensee is addressed as "you".
+
+A "library" means a collection of software functions and/or data prepared so as to be conveniently linked with application programs (which use some of those functions and data) to form executables.
+
+The "Library", below, refers to any such software library or work which has been distributed under these terms. A "work based on the Library" means either the Library or any derivative work under copyright law: that is to say, a work containing the Library or a portion of it, either verbatim or with modifications and/or translated straightforwardly into another language. (Hereinafter, translation is included without limitation in the term "modification".)
+
+"Source code" for a work means the preferred form of the work for making modifications to it. For a library, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the library.
+
+Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running a program using the Library is not restricted, and output from such a program is covered only if its contents constitute a work based on the Library (independent of the use of the Library in a tool for writing it). Whether that is true depends on what the Library does and what the program that uses the Library does.
+
+1. You may copy and distribute verbatim copies of the Library's complete source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and distribute a copy of this License along with the Library.
+
+You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.
+
+2. You may modify your copy or copies of the Library or any portion of it, thus forming a work based on the Library, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:
+
+     a) The modified work must itself be a software library.
+
+     b) You must cause the files modified to carry prominent notices stating that you changed the files and the date of any change.
+
+     c) You must cause the whole of the work to be licensed at no charge to all third parties under the terms of this License.
+
+     d) If a facility in the modified Library refers to a function or a table of data to be supplied by an application program that uses the facility, other than as an argument passed when the facility is invoked, then you must make a good faith effort to ensure that, in the event an application does not supply such function or table, the facility still operates, and performs whatever part of its purpose remains meaningful.
+
+(For example, a function in a library to compute square roots has a purpose that is entirely well-defined independent of the application. Therefore, Subsection 2d requires that any application-supplied function or table used by this function must be optional: if the application does not supply it, the square root function must still compute square roots.)
+
+These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Library, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Library, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Library.
+
+In addition, mere aggregation of another work not based on the Library with the Library (or with a work based on the Library) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.
+
+3. You may opt to apply the terms of the ordinary GNU General Public License instead of this License to a given copy of the Library. To do this, you must alter all the notices that refer to this License, so that they refer to the ordinary GNU General Public License, version 2, instead of to this License. (If a newer version than version 2 of the ordinary GNU General Public License has appeared, then you can specify that version instead if you wish.) Do not make any other change in these notices.
+
+Once this change is made in a given copy, it is irreversible for that copy, so the ordinary GNU General Public License applies to all subsequent copies and derivative works made from that copy.
+
+This option is useful when you wish to copy part of the code of the Library into a program that is not a library.
+
+4. You may copy and distribute the Library (or a portion or derivative of it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange.
+
+If distribution of object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place satisfies the requirement to distribute the source code, even though third parties are not compelled to copy the source along with the object code.
+
+5. A program that contains no derivative of any portion of the Library, but is designed to work with the Library by being compiled or linked with it, is called a "work that uses the Library". Such a work, in isolation, is not a derivative work of the Library, and therefore falls outside the scope of this License.
+
+However, linking a "work that uses the Library" with the Library creates an executable that is a derivative of the Library (because it contains portions of the Library), rather than a "work that uses the library". The executable is therefore covered by this License. Section 6 states terms for distribution of such executables.
+
+When a "work that uses the Library" uses material from a header file that is part of the Library, the object code for the work may be a derivative work of the Library even though the source code is not. Whether this is true is especially significant if the work can be linked without the Library, or if the work is itself a library. The threshold for this to be true is not precisely defined by law.
+
+If such an object file uses only numerical parameters, data structure layouts and accessors, and small macros and small inline functions (ten lines or less in length), then the use of the object file is unrestricted, regardless of whether it is legally a derivative work. (Executables containing this object code plus portions of the Library will still fall under Section 6.)
+
+Otherwise, if the work is a derivative of the Library, you may distribute the object code for the work under the terms of Section 6. Any executables containing that work also fall under Section 6, whether or not they are linked directly with the Library itself.
+
+6. As an exception to the Sections above, you may also combine or link a "work that uses the Library" with the Library to produce a work containing portions of the Library, and distribute that work under terms of your choice, provided that the terms permit modification of the work for the customer's own use and reverse engineering for debugging such modifications.
+
+You must give prominent notice with each copy of the work that the Library is used in it and that the Library and its use are covered by this License. You must supply a copy of this License. If the work during execution displays copyright notices, you must include the copyright notice for the Library among them, as well as a reference directing the user to the copy of this License. Also, you must do one of these things:
+
+     a) Accompany the work with the complete corresponding machine-readable source code for the Library including whatever changes were used in the work (which must be distributed under Sections 1 and 2 above); and, if the work is an executable linked with the Library, with the complete machine-readable "work that uses the Library", as object code and/or source code, so that the user can modify the Library and then relink to produce a modified executable containing the modified Library. (It is understood that the user who changes the contents of definitions files in the Library will not necessarily be able to recompile the application to use the modified definitions.)
+
+     b) Use a suitable shared library mechanism for linking with the Library. A suitable mechanism is one that (1) uses at run time a copy of the library already present on the user's computer system, rather than copying library functions into the executable, and (2) will operate properly with a modified version of the library, if the user installs one, as long as the modified version is interface-compatible with the version that the work was made with.
+
+     c) Accompany the work with a written offer, valid for at least three years, to give the same user the materials specified in Subsection 6a, above, for a charge no more than the cost of performing this distribution.
+
+     d) If distribution of the work is made by offering access to copy from a designated place, offer equivalent access to copy the above specified materials from the same place.
+
+     e) Verify that the user has already received a copy of these materials or that you have already sent this user a copy.
+
+For an executable, the required form of the "work that uses the Library" must include any data and utility programs needed for reproducing the executable from it. However, as a special exception, the materials to be distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.
+
+It may happen that this requirement contradicts the license restrictions of other proprietary libraries that do not normally accompany the operating system. Such a contradiction means you cannot use both them and the Library together in an executable that you distribute.
+
+7. You may place library facilities that are a work based on the Library side-by-side in a single library together with other library facilities not covered by this License, and distribute such a combined library, provided that the separate distribution of the work based on the Library and of the other library facilities is otherwise permitted, and provided that you do these two things:
+
+     a) Accompany the combined library with a copy of the same work based on the Library, uncombined with any other library facilities. This must be distributed under the terms of the Sections above.
+
+     b) Give prominent notice with the combined library of the fact that part of it is a work based on the Library, and explaining where to find the accompanying uncombined form of the same work.
+
+8. You may not copy, modify, sublicense, link with, or distribute the Library except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, link with, or distribute the Library is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
+
+9. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Library or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Library (or any work based on the Library), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Library or works based on it.
+
+10. Each time you redistribute the Library (or any work based on the Library), the recipient automatically receives a license from the original licensor to copy, distribute, link with or modify the Library subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties with this License.
+
+11. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Library at all. For example, if a patent license would not permit royalty-free redistribution of the Library by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Library.
+
+If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply, and the section as a whole is intended to apply in other circumstances.
+
+It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.
+
+This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.
+
+12. If the distribution and/or use of the Library is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Library under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.
+
+13. The Free Software Foundation may publish revised and/or new versions of the Lesser General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number. If the Library specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Library does not specify a license version number, you may choose any version ever published by the Free Software Foundation.
+
+14. If you wish to incorporate parts of the Library into other free programs whose distribution conditions are incompatible with these, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.
+
+NO WARRANTY
+
+15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+END OF TERMS AND CONDITIONS
+
+How to Apply These Terms to Your New Libraries
+
+If you develop a new library, and you want it to be of the greatest possible use to the public, we recommend making it free software that everyone can redistribute and change. You can do so by permitting redistribution under these terms (or, alternatively, under the terms of the ordinary General Public License).
+
+To apply these terms, attach the following notices to the library. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.
+
+     one line to give the library's name and an idea of what it does.
+     Copyright (C) year  name of author
+
+     This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.
+
+     This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
+
+     You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA Also add information on how to contact you by electronic and paper mail.
+
+You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the library, if necessary. Here is a sample; alter the names:
+
+Yoyodyne, Inc., hereby disclaims all copyright interest in
+the library `Frob' (a library for tweaking knobs) written
+by James Random Hacker.
+
+signature of Ty Coon, 1 April 1990
+Ty Coon, President of Vice
+That's all there is to it!

LICENSES/MPL-1.1.txt

@@ -0,0 +1,143 @@
+Mozilla Public License Version 1.1
+
+1. Definitions.
+
+     1.0.1. "Commercial Use" means distribution or otherwise making the Covered Code available to a third party.
+
+     1.1. "Contributor" means each entity that creates or contributes to the creation of Modifications.
+
+     1.2. "Contributor Version" means the combination of the Original Code, prior Modifications used by a Contributor, and the Modifications made by that particular Contributor.
+
+     1.3. "Covered Code" means the Original Code or Modifications or the combination of the Original Code and Modifications, in each case including portions thereof.
+
+     1.4. "Electronic Distribution Mechanism" means a mechanism generally accepted in the software development community for the electronic transfer of data.
+
+     1.5. "Executable" means Covered Code in any form other than Source Code.
+
+     1.6. "Initial Developer" means the individual or entity identified as the Initial Developer in the Source Code notice required by Exhibit A.
+
+     1.7. "Larger Work" means a work which combines Covered Code or portions thereof with code not governed by the terms of this License.
+
+     1.8. "License" means this document.
+
+     1.8.1. "Licensable" means having the right to grant, to the maximum extent possible, whether at the time of the initial grant or subsequently acquired, any and all of the rights conveyed herein.
+
+     1.9. "Modifications" means any addition to or deletion from the substance or structure of either the Original Code or any previous Modifications. When Covered Code is released as a series of files, a Modification is:
+Any addition to or deletion from the contents of a file containing Original Code or previous Modifications.
+Any new file that contains any part of the Original Code or previous Modifications.
+
+     1.10. "Original Code" means Source Code of computer software code which is described in the Source Code notice required by Exhibit A as Original Code, and which, at the time of its release under this License is not already Covered Code governed by this License.
+
+     1.10.1. "Patent Claims" means any patent claim(s), now owned or hereafter acquired, including without limitation, method, process, and apparatus claims, in any patent Licensable by grantor.
+
+     1.11. "Source Code" means the preferred form of the Covered Code for making modifications to it, including all modules it contains, plus any associated interface definition files, scripts used to control compilation and installation of an Executable, or source code differential comparisons against either the Original Code or another well known, available Covered Code of the Contributor's choice. The Source Code can be in a compressed or archival form, provided the appropriate decompression or de-archiving software is widely available for no charge.
+
+     1.12. "You" (or "Your") means an individual or a legal entity exercising rights under, and complying with all of the terms of, this License or a future version of this License issued under Section 6.1. For legal entities, "You" includes any entity which controls, is controlled by, or is under common control with You. For purposes of this definition, "control" means (a) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (b) ownership of more than fifty percent (50%) of the outstanding shares or beneficial ownership of such entity.
+
+2. Source Code License.
+
+     2.1. The Initial Developer Grant. The Initial Developer hereby grants You a world-wide, royalty-free, non-exclusive license, subject to third party intellectual property claims:
+
+          a. under intellectual property rights (other than patent or trademark) Licensable by Initial Developer to use, reproduce, modify, display, perform, sublicense and distribute the Original Code (or portions thereof) with or without Modifications, and/or as part of a Larger Work; and
+          b. under Patents Claims infringed by the making, using or selling of Original Code, to make, have made, use, practice, sell, and offer for sale, and/or otherwise dispose of the Original Code (or portions thereof).
+          c. the licenses granted in this Section 2.1 (a) and (b) are effective on the date Initial Developer first distributes Original Code under the terms of this License.
+          d. Notwithstanding Section 2.1 (b) above, no patent license is granted: 1) for code that You delete from the Original Code; 2) separate from the Original Code; or 3) for infringements caused by: i) the modification of the Original Code or ii) the combination of the Original Code with other software or devices.
+
+     2.2. Contributor Grant. Subject to third party intellectual property claims, each Contributor hereby grants You a world-wide, royalty-free, non-exclusive license
+
+          a. under intellectual property rights (other than patent or trademark) Licensable by Contributor, to use, reproduce, modify, display, perform, sublicense and distribute the Modifications created by such Contributor (or portions thereof) either on an unmodified basis, with other Modifications, as Covered Code and/or as part of a Larger Work; and
+          b. under Patent Claims infringed by the making, using, or selling of Modifications made by that Contributor either alone and/or in combination with its Contributor Version (or portions of such combination), to make, use, sell, offer for sale, have made, and/or otherwise dispose of: 1) Modifications made by that Contributor (or portions thereof); and 2) the combination of Modifications made by that Contributor with its Contributor Version (or portions of such combination).
+          c. the licenses granted in Sections 2.2 (a) and 2.2 (b) are effective on the date Contributor first makes Commercial Use of the Covered Code.
+          d. Notwithstanding Section 2.2 (b) above, no patent license is granted: 1) for any code that Contributor has deleted from the Contributor Version; 2) separate from the Contributor Version; 3) for infringements caused by: i) third party modifications of Contributor Version or ii) the combination of Modifications made by that Contributor with other software (except as part of the Contributor Version) or other devices; or 4) under Patent Claims infringed by Covered Code in the absence of Modifications made by that Contributor.
+
+3. Distribution Obligations.
+
+     3.1. Application of License. The Modifications which You create or to which You contribute are governed by the terms of this License, including without limitation Section 2.2. The Source Code version of Covered Code may be distributed only under the terms of this License or a future version of this License released under Section 6.1, and You must include a copy of this License with every copy of the Source Code You distribute. You may not offer or impose any terms on any Source Code version that alters or restricts the applicable version of this License or the recipients' rights hereunder. However, You may include an additional document offering the additional rights described in Section 3.5.
+
+     3.2. Availability of Source Code. Any Modification which You create or to which You contribute must be made available in Source Code form under the terms of this License either on the same media as an Executable version or via an accepted Electronic Distribution Mechanism to anyone to whom you made an Executable version available; and if made available via Electronic Distribution Mechanism, must remain available for at least twelve (12) months after the date it initially became available, or at least six (6) months after a subsequent version of that particular Modification has been made available to such recipients. You are responsible for ensuring that the Source Code version remains available even if the Electronic Distribution Mechanism is maintained by a third party.
+
+     3.3. Description of Modifications. You must cause all Covered Code to which You contribute to contain a file documenting the changes You made to create that Covered Code and the date of any change. You must include a prominent statement that the Modification is derived, directly or indirectly, from Original Code provided by the Initial Developer and including the name of the Initial Developer in (a) the Source Code, and (b) in any notice in an Executable version or related documentation in which You describe the origin or ownership of the Covered Code.
+
+     3.4. Intellectual Property Matters
+
+          (a) Third Party Claims
+          If Contributor has knowledge that a license under a third party's intellectual property rights is required to exercise the rights granted by such Contributor under Sections 2.1 or 2.2, Contributor must include a text file with the Source Code distribution titled "LEGAL" which describes the claim and the party making the claim in sufficient detail that a recipient will know whom to contact. If Contributor obtains such knowledge after the Modification is made available as described in Section 3.2, Contributor shall promptly modify the LEGAL file in all copies Contributor makes available thereafter and shall take other steps (such as notifying appropriate mailing lists or newsgroups) reasonably calculated to inform those who received the Covered Code that new knowledge has been obtained.
+
+          (b) Contributor APIs
+          If Contributor's Modifications include an application programming interface and Contributor has knowledge of patent licenses which are reasonably necessary to implement that API, Contributor must also include this information in the LEGAL file.
+
+          (c) Representations.
+          Contributor represents that, except as disclosed pursuant to Section 3.4 (a) above, Contributor believes that Contributor's Modifications are Contributor's original creation(s) and/or Contributor has sufficient rights to grant the rights conveyed by this License.
+
+     3.5. Required Notices. You must duplicate the notice in Exhibit A in each file of the Source Code. If it is not possible to put such notice in a particular Source Code file due to its structure, then You must include such notice in a location (such as a relevant directory) where a user would be likely to look for such a notice. If You created one or more Modification(s) You may add your name as a Contributor to the notice described in Exhibit A. You must also duplicate this License in any documentation for the Source Code where You describe recipients' rights or ownership rights relating to Covered Code. You may choose to offer, and to charge a fee for, warranty, support, indemnity or liability obligations to one or more recipients of Covered Code. However, You may do so only on Your own behalf, and not on behalf of the Initial Developer or any Contributor. You must make it absolutely clear than any such warranty, support, indemnity or liability obligation is offered by You alone, and You hereby agree to indemnify the Initial Developer and every Contributor for any liability incurred by the Initial Developer or such Contributor as a result of warranty, support, indemnity or liability terms You offer.
+
+     3.6. Distribution of Executable Versions. You may distribute Covered Code in Executable form only if the requirements of Sections 3.1, 3.2, 3.3, 3.4 and 3.5 have been met for that Covered Code, and if You include a notice stating that the Source Code version of the Covered Code is available under the terms of this License, including a description of how and where You have fulfilled the obligations of Section 3.2. The notice must be conspicuously included in any notice in an Executable version, related documentation or collateral in which You describe recipients' rights relating to the Covered Code. You may distribute the Executable version of Covered Code or ownership rights under a license of Your choice, which may contain terms different from this License, provided that You are in compliance with the terms of this License and that the license for the Executable version does not attempt to limit or alter the recipient's rights in the Source Code version from the rights set forth in this License. If You distribute the Executable version under a different license You must make it absolutely clear that any terms which differ from this License are offered by You alone, not by the Initial Developer or any Contributor. You hereby agree to indemnify the Initial Developer and every Contributor for any liability incurred by the Initial Developer or such Contributor as a result of any such terms You offer.
+
+     3.7. Larger Works. You may create a Larger Work by combining Covered Code with other code not governed by the terms of this License and distribute the Larger Work as a single product. In such a case, You must make sure the requirements of this License are fulfilled for the Covered Code.
+
+4. Inability to Comply Due to Statute or Regulation.
+
+If it is impossible for You to comply with any of the terms of this License with respect to some or all of the Covered Code due to statute, judicial order, or regulation then You must: (a) comply with the terms of this License to the maximum extent possible; and (b) describe the limitations and the code they affect. Such description must be included in the LEGAL file described in Section 3.4 and must be included with all distributions of the Source Code. Except to the extent prohibited by statute or regulation, such description must be sufficiently detailed for a recipient of ordinary skill to be able to understand it.
+
+5. Application of this License.
+This License applies to code to which the Initial Developer has attached the notice in Exhibit A and to related Covered Code.
+
+6. Versions of the License.
+
+     6.1. New Versions
+     Netscape Communications Corporation ("Netscape") may publish revised and/or new versions of the License from time to time. Each version will be given a distinguishing version number.
+
+     6.2. Effect of New Versions
+     Once Covered Code has been published under a particular version of the License, You may always continue to use it under the terms of that version. You may also choose to use such Covered Code under the terms of any subsequent version of the License published by Netscape. No one other than Netscape has the right to modify the terms applicable to Covered Code created under this License.
+
+     6.3. Derivative Works
+     If You create or use a modified version of this License (which you may only do in order to apply it to code which is not already Covered Code governed by this License), You must (a) rename Your license so that the phrases "Mozilla", "MOZILLAPL", "MOZPL", "Netscape", "MPL", "NPL" or any confusingly similar phrase do not appear in your license (except to note that your license differs from this License) and (b) otherwise make it clear that Your version of the license contains terms which differ from the Mozilla Public License and Netscape Public License. (Filling in the name of the Initial Developer, Original Code or Contributor in the notice described in Exhibit A shall not of themselves be deemed to be modifications of this License.)
+
+7. DISCLAIMER OF WARRANTY
+COVERED CODE IS PROVIDED UNDER THIS LICENSE ON AN "AS IS" BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, WARRANTIES THAT THE COVERED CODE IS FREE OF DEFECTS, MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE OR NON-INFRINGING. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE COVERED CODE IS WITH YOU. SHOULD ANY COVERED CODE PROVE DEFECTIVE IN ANY RESPECT, YOU (NOT THE INITIAL DEVELOPER OR ANY OTHER CONTRIBUTOR) ASSUME THE COST OF ANY NECESSARY SERVICING, REPAIR OR CORRECTION. THIS DISCLAIMER OF WARRANTY CONSTITUTES AN ESSENTIAL PART OF THIS LICENSE. NO USE OF ANY COVERED CODE IS AUTHORIZED HEREUNDER EXCEPT UNDER THIS DISCLAIMER.
+
+8. Termination
+
+     8.1. This License and the rights granted hereunder will terminate automatically if You fail to comply with terms herein and fail to cure such breach within 30 days of becoming aware of the breach. All sublicenses to the Covered Code which are properly granted shall survive any termination of this License. Provisions which, by their nature, must remain in effect beyond the termination of this License shall survive.
+
+     8.2. If You initiate litigation by asserting a patent infringement claim (excluding declatory judgment actions) against Initial Developer or a Contributor (the Initial Developer or Contributor against whom You file such action is referred to as "Participant") alleging that:
+
+          a. such Participant's Contributor Version directly or indirectly infringes any patent, then any and all rights granted by such Participant to You under Sections 2.1 and/or 2.2 of this License shall, upon 60 days notice from Participant terminate prospectively, unless if within 60 days after receipt of notice You either: (i) agree in writing to pay Participant a mutually agreeable reasonable royalty for Your past and future use of Modifications made by such Participant, or (ii) withdraw Your litigation claim with respect to the Contributor Version against such Participant. If within 60 days of notice, a reasonable royalty and payment arrangement are not mutually agreed upon in writing by the parties or the litigation claim is not withdrawn, the rights granted by Participant to You under Sections 2.1 and/or 2.2 automatically terminate at the expiration of the 60 day notice period specified above.
+          b. any software, hardware, or device, other than such Participant's Contributor Version, directly or indirectly infringes any patent, then any rights granted to You by such Participant under Sections 2.1(b) and 2.2(b) are revoked effective as of the date You first made, used, sold, distributed, or had made, Modifications made by that Participant.
+
+     8.3. If You assert a patent infringement claim against Participant alleging that such Participant's Contributor Version directly or indirectly infringes any patent where such claim is resolved (such as by license or settlement) prior to the initiation of patent infringement litigation, then the reasonable value of the licenses granted by such Participant under Sections 2.1 or 2.2 shall be taken into account in determining the amount or value of any payment or license.
+
+     8.4. In the event of termination under Sections 8.1 or 8.2 above, all end user license agreements (excluding distributors and resellers) which have been validly granted by You or any distributor hereunder prior to termination shall survive termination.
+
+9. LIMITATION OF LIABILITY
+UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL THEORY, WHETHER TORT (INCLUDING NEGLIGENCE), CONTRACT, OR OTHERWISE, SHALL YOU, THE INITIAL DEVELOPER, ANY OTHER CONTRIBUTOR, OR ANY DISTRIBUTOR OF COVERED CODE, OR ANY SUPPLIER OF ANY OF SUCH PARTIES, BE LIABLE TO ANY PERSON FOR ANY INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR MALFUNCTION, OR ANY AND ALL OTHER COMMERCIAL DAMAGES OR LOSSES, EVEN IF SUCH PARTY SHALL HAVE BEEN INFORMED OF THE POSSIBILITY OF SUCH DAMAGES. THIS LIMITATION OF LIABILITY SHALL NOT APPLY TO LIABILITY FOR DEATH OR PERSONAL INJURY RESULTING FROM SUCH PARTY'S NEGLIGENCE TO THE EXTENT APPLICABLE LAW PROHIBITS SUCH LIMITATION. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THIS EXCLUSION AND LIMITATION MAY NOT APPLY TO YOU.
+
+10. U.S. government end users
+The Covered Code is a "commercial item," as that term is defined in 48 C.F.R. 2.101 (Oct. 1995), consisting of "commercial computer software" and "commercial computer software documentation," as such terms are used in 48 C.F.R. 12.212 (Sept. 1995). Consistent with 48 C.F.R. 12.212 and 48 C.F.R. 227.7202-1 through 227.7202-4 (June 1995), all U.S. Government End Users acquire Covered Code with only those rights set forth herein.
+
+11. Miscellaneous
+This License represents the complete agreement concerning subject matter hereof. If any provision of this License is held to be unenforceable, such provision shall be reformed only to the extent necessary to make it enforceable. This License shall be governed by California law provisions (except to the extent applicable law, if any, provides otherwise), excluding its conflict-of-law provisions. With respect to disputes in which at least one party is a citizen of, or an entity chartered or registered to do business in the United States of America, any litigation relating to this License shall be subject to the jurisdiction of the Federal Courts of the Northern District of California, with venue lying in Santa Clara County, California, with the losing party responsible for costs, including without limitation, court costs and reasonable attorneys' fees and expenses. The application of the United Nations Convention on Contracts for the International Sale of Goods is expressly excluded. Any law or regulation which provides that the language of a contract shall be construed against the drafter shall not apply to this License.
+
+12. Responsibility for claims
+As between Initial Developer and the Contributors, each party is responsible for claims and damages arising, directly or indirectly, out of its utilization of rights under this License and You agree to work with Initial Developer and Contributors to distribute such responsibility on an equitable basis. Nothing herein is intended or shall be deemed to constitute any admission of liability.
+
+13. Multiple-licensed code
+Initial Developer may designate portions of the Covered Code as "Multiple-Licensed". "Multiple-Licensed" means that the Initial Developer permits you to utilize portions of the Covered Code under Your choice of the MPL or the alternative licenses, if any, specified by the Initial Developer in the file described in Exhibit A.
+
+Exhibit A - Mozilla Public License.
+
+"The contents of this file are subject to the Mozilla Public License Version 1.1 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.mozilla.org/MPL/
+
+Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License.
+
+The Original Code is ______________________________________.
+
+The Initial Developer of the Original Code is ________________________.
+Portions created by ______________________ are Copyright (C) ______
+_______________________. All Rights Reserved.
+
+Contributor(s): ______________________________________.
+
+Alternatively, the contents of this file may be used under the terms of the _____ license (the  "[___] License"), in which case the provisions of [______] License are applicable instead of those above. If you wish to allow use of your version of this file only under the terms of the [____] License and not to allow others to use your version of this file under the MPL, indicate your decision by deleting the provisions above and replace them with the notice and other provisions required by the [___] License. If you do not delete the provisions above, a recipient may use your version of this file under either the MPL or the [___] License."
+
+NOTE: The text of this Exhibit A may differ slightly from the text of the notices in the Source Code files of the Original Code. You should use the text of this Exhibit A rather than the text found in the Original Code Source Code for Your Modifications.

NEWS

@@ -1,85 +1,518 @@
-Overview of changes in GLib 2.78.3, 2023-12-06
+Overview of changes in GLib 2.80.0, 2024-03-07
-==============================================
-
-* Fix a crash-causing regression in xdgmime (#3191, work by Philip Withnall)
-
-* Bugs fixed:
-  - #3191 Crash in __gio_xdg_cache_mime_type_subclass (Philip Withnall)
-  - !3747 Backport !3742 “xdgmime: Update to upstream commit c2c814d4051f232” to
-    glib-2-78
-
-
-Overview of changes in GLib 2.78.2, 2023-12-05
 ==============================================
 
 * Bugs fixed:
+  - #3271 GLib: string malformed for gettext (Philip Withnall)
+  - !3940 tests: Don’t run check-missing-install-tag.py test under valgrind
+    (Philip Withnall)
+  - !3946 Add missing argument placeholders to several command-line tools (Simon
+    McVittie)
+  - !3947 docs: Fix a typo in the macros docs page (Philip Withnall)
+  - !3951 g_warn_if_fail: Document as always evaluating expr (Simon McVittie)
+  - !3953 docs: Specify gi-docgen as a native dependency (Bobby Rong)
+  - !3955 docs: Fix building with docs enabled and introspection disabled (Bobby
+    Rong)
+  - !3956 docs: Minor improvements to GSignal documentation (Philip Withnall)
+
+* Translation updates:
+  - Basque (Asier Sarasua Garmendia)
+  - British English (Andi Chandler, Bruce Cowan)
+  - Chinese (China) (Luming Zh)
+  - Czech (Daniel Rusek)
+  - Georgian (Ekaterine Papava)
+  - Hebrew (Yaron Shahrabani)
+  - Hungarian (Balázs Úr)
+  - Kazakh (Baurzhan Muftakhidinov)
+  - Lithuanian (Aurimas Černius)
+  - Norwegian Bokmål (Brage Fuglseth)
+  - Persian (Danial Behzadi)
+  - Russian (Artur S0)
+  - Slovenian (Matej Urbančič)
+  - Spanish (Daniel Mustieles)
+  - Swedish (Anders Jonsson)
+  - Turkish (Sabri Ünal)
+  - Ukrainian (Yuri Chornoivan)
+
+
+Overview of changes in GLib 2.79.3, 2024-02-27
+==============================================
+
+* Various consistency improvements to the command line libgirepository tools
+  (!3926, !3927, !3928, !3930, work by Simon McVittie)
+
+* Bugs fixed:
+  - #3080 Gimp GTK file chooser hang when a remote file is open (Luca Bacci)
+  - #3210 Critical using Open location: GWinHttpFile doesn’t set
+    G_FILE_ATTRIBUTE_STANDARD_TYPE (Luca Bacci)
+  - #3252 [2.79.1] gdatetime installed tests fails on s390x (Simon McVittie)
+  - #3255 g_base_info_clear on zero-initialized stack-allocated introspection
+    info (Philip Withnall)
+  - #3258 Possible memory leak in GUnixVolumeMonitor (Ondrej Holy)
+  - #3260 Add man pages for girepository tools
+  - #3262 msys2-mingw32 build failing with error code 3221225785 (0xc0000139)
+    (Philip Withnall)
+  - #3263 Ensure girepository tools are translatable (Philip Withnall)
+  - #3266 Use-after-free in gsocketclient.c:connection_attempt_remove() (Philip
+    Withnall)
+  - #3271 GLib: string malformed for gettext (Philip Withnall)
+  - !3918 tests: Don’t run lint tests under valgrind
+  - !3919 tests: Speed up threaded toggle notify test unless -m slow is passed
+  - !3921 ci: Fix printing the execution environment
+  - !3922 gdatetime test: Produce more helpful output on mismatches
+  - !3923 girepository test: Don't assume doubles are naturally-aligned
+  - !3925 girwriter: Take the GIRepository as a parameter
+  - !3926 gi- tools: Remove unused options, improve --debug/--verbose
+  - !3927 g-ir-compiler: Only accept one input file
+  - !3928 gi-decompile-typelib: Interpret --includedir as most-important-first
+  - !3930 migrating-gi: Document command-line option removals
+  - !3935 Restrict macOS CI to origin
+  - !3937 girepository: Fix static build under Windows
+  - !3945 tests: Remove variable-length lookbehind tests for GRegex
+
+* Translation updates:
+  - Basque (Asier Sarasua Garmendia)
+  - Catalan (Jordi Mas i Hernandez)
+  - Chinese (China) (Boyuan Yang)
+  - Czech (Daniel Rusek)
+  - Galician (Fran Dieguez)
+  - Georgian (Ekaterine Papava)
+  - Hebrew (Yaron Shahrabani)
+  - Indonesian (Andika Triwidada)
+  - Kazakh (Baurzhan Muftakhidinov)
+  - Latvian (Rūdolfs Mazurs)
+  - Lithuanian (Aurimas Černius)
+  - Persian (Danial Behzadi)
+  - Russian (Artur S0)
+  - Slovenian (Matej Urbančič)
+  - Spanish (Daniel Mustieles)
+  - Turkish (Sabri Ünal, Emin Tufan Çetin)
+  - Ukrainian (Yuri Chornoivan)
+
+
+Overview of changes in GLib 2.79.2, 2024-02-12
+==============================================
+
+* More work to reduce lock contention and improve performance in GObject (#743,
+  !3869, !3873, work by Thomas Haller)
+
+* More API changes to libgirepository, which is now stable as of this release
+  (#3155, #3217, #3218, #3231, #3234, #3243, #3244, #3245, #3246, work by
+  Philip Chimento, Evan Welsh, Philip Withnall)
+
+* Import `g-ir-compiler`, `g-ir-generate` and `g-ir-inspect` from
+  gobject-introspection.git and update them to work with girepository-2.0,
+  renaming them to `gi-compile-repository`, `gi-decompile-typelib` and
+  `gi-inspect-typelib` (see docs/reference/girepository/migrating-gi.md) (!3853,
+  !3909, work by Evan Welsh, Philip Withnall)
+
+* Add new `GLibUnix-2.0.gir`, `GLibWin32-2.0.gir`, `GioUnix-2.0.gir` and
+  `GioWin32-2.0.gir` GIRs which contain platform specific APIs, and are the
+  preferred way for third parties to access those APIs in future; although
+  platform specific APIs which were already exposed in `GLib-2.0.gir` and
+  `Gio-2.0.gir` continue to be listed there; the underlying `.so` files have not
+  changed (!3892, work by Philip Withnall)
+
+* Bugs fixed:
+  - #743 GLib weak refs depend on cascade of locks, including global ones, which
+    makes them non-scalable
+  - #2887 memory-monitor-dbus.test fails in installed-tests suite (Philip
+    Withnall)
+  - #3198 Support --version in standard GApplication command line arguments
+    (Maxim Moskalets)
+  - #3217 Feedback on gobject-introspection: APIs for stack-allocated
+    introspection info (Philip Withnall)
+  - #3218 Segfault in gi_function_info_prep_invoker (Philip Withnall)
+  - #3231 New functions in the glib introspection data (Philip Withnall)
+  - #3234 Reference cycle between GIRepository and GIBaseInfos cached by it
+    (Philip Withnall)
+  - #3236 threaded_resolver_worker_cb leaks memory when lookup fails and
+    connection is already canceled (Philip Withnall)
+  - #3238 Python packaging module is missing on Hurd CI runner (Philip Withnall)
+  - #3240 Missing preconditions checks in GArray (Tobias Stoeckmann)
+  - #3242 Memory leak in gresources over libelf (Maxim Moskalets)
+  - #3243 Feedback on girepository 2.0: Naming of get_type_info vs load_type
+    (Philip Withnall)
+  - #3244 Feedback on girepository 2.0: Where to find uninstalled typelibs
+    (Philip Withnall)
+  - #3245 Feedback on girepository 2.0: GIBoxedInfo's place in the type
+    hierarchy (Philip Withnall)
+  - #3246 Wrong out parameter type in
+    gi_object_info_find_method_using_interfaces (Philip Withnall)
+  - #3247 safe_closefrom(), safe_fdwalk_set_cloexec() as public API (Simon
+    McVittie)
+  - !3797 Refactor GIRepository GIR generation to avoid cyclical dependency
+  - !3807 gprintf/gstrfuncs: Improve and port doc comments to gi-docgen
+  - !3824 gconvert: match GNU iconv behaviour on FreeBSD
+  - !3838 build: Add thorough test setup
+  - !3843 Add more test coverage for girepository
+  - !3845 gunixmounts: Use libmnt_monitor API for monitoring
+  - !3847 ci: Add ability to run manually some specific jobs
+  - !3848 Fix build with introspection on Windows
+  - !3849 girepository: Remove GI_FUNCTION_THROWS and GI_VFUNC_THROWS flags
+  - !3850 [th/strdup-in-ascii-strdown] glib: use g_strdup() in
+    g_ascii_strdown(),g_ascii_strup()
+  - !3851 ci: Fix post-merge CI pipelines
+  - !3853 girepository: Update gir-compiler and use it to compile GIRs
+  - !3854 girnode: Document ownership and element types of internal structs
+  - !3855 gitypelib: Replace multiple constructors with
+    gi_typelib_new_from_bytes()
+  - !3856 girepository: Drop gi_repository_get_default()
+  - !3859 [th/glib-private-const] glib: return const pointer from
+    glib__private__()
+  - !3860 tests: Fix typo in memory-monitor-portal.py.in
+  - !3861 girepository: Fix a memory leak of a mapped file
+  - !3865 [th/test-weak-notify] gobject/tests: add test checking that GWeakRef
+    is cleared in GWeakNotify
+  - !3866 [th/gobject-carray-comment] gobject: remove obsolete code comment
+    about CArray
+  - !3868 Link to the main context tutorial from the main loop docs
+  - !3869 [th/optimize-weak-ref-list] rework GObject's `WeakRefData` to track
+    references in an array instead of GSList
+  - !3870 Revert "Don't skip dbus-codegen tests on Win32"
+  - !3871 docs: Fix include path for the build
+  - !3872 gio: tests: Use slightly more explicit assert functions
+  - !3873 [th/datalist-shrink] shrink the interal buffer of `GData`
+  - !3874 Don't skip dbus-codegen tests on Win32
+  - !3876 build: Only override g-ir-compiler when GIR generation is enabled
+  - !3877 Various girepository fixes
+  - !3879 [th/gdataset-comment] gdataset: add code comment to
+    g_datalist_get_data()
+  - !3881 docs: Add migration guide for libgirepository
+  - !3886 codegen: Use `-` instead of `stdout` for output to stdout
+  - !3887 gtestutils: Ensure test_data is freed even if a test is skipped
+  - !3888 gitypes: Fix integer values of GIInfoType and add unit tests for
+    GIUnionInfo
+  - !3892 introspection: Generate separate GIR files and documentation for
+    platform specific APIs
+  - !3893 glocalfile: Support statvfs.f_type
+  - !3894 Minor fixes/docs changes to GFileDescriptorBased and GTask
+  - !3895 [th/meson-werror-fixes] some fixes for meson detection failure with
+    -Werror
+  - !3896 reuse: Add dep5 lines for gnulib and libcharset
+  - !3897 reuse: Fix screen-scraping expression for version 2.x
+  - !3898 Incorporate some lint checks into `meson test`
+  - !3900 gitypelib: Switch to refcounting
+  - !3901 girepository: Add length ‘out’ arguments to several getter methods
+  - !3902 gicallableinfo: Clarify docs for callables with no return type
+  - !3903 gibaseinfo: Rename gi_info_new() to gi_base_info_new()
+  - !3904 [th/meson-werror-fixes-2] more workarounds for compiler warnings in
+    meson compiler checks
+  - !3909 Rename g-ir-generate and g-ir-inspect and update to girepository-2.0
+  - !3911 glib/tests/unix: Mostly pass O_CLOEXEC to g_unix_pipe_open()
+  - !3912 glib-unix: Fix reference to FD_CLOEXEC in docs for g_unix_pipe_open()
+  - !3913 cmph: Fix a typo
+  - !3914 Revert "ci: Remove not-printable chars from generated junit file"
+  - !3916 tests: Skip lint tests if bash is not available
+  - !3917 ci: Build and tar libgirepository documentation
+
+* Translation updates:
+  - Georgian (Ekaterine Papava)
+  - Russian (Artur S0)
+
+
+Overview of changes in GLib 2.79.1, 2024-01-22
+==============================================
+
+* Fix a race condition in `g_object_unref()` (#3064, work by Thomas Haller)
+
+* Various API and build changes to libgirepository as it is not yet API-stable
+  (#3216, !3780, !3805, !3823, !3833, !3840)
+
+* Build fixes on big-endian 64-bit systems and mips64el (#3225, #3226, work by
+  Simon McVittie)
+
+* Reduce contention on global locks within GObject (!3774, work by Thomas
+  Haller)
+
+* Allow building man pages without the reference documentation (!3817, work by
+  Simon McVittie)
+
+* Bugs fixed:
+  - #1010 g_get_num_processor does not respect cpuset/affinity
+  - #3064 Crash under g_object_unref()
+  - #3093 GDBusMessage: should validate the type of all known headers (Philip
+    Withnall)
+  - #3207 Add support for syslog to Structured Logging
+  - #3216 Feedback on gobject-introspection: Casting to and from GIBaseInfo*
+    (Philip Withnall)
+  - #3222 pthread_t usages lack type name (Emmanuele Bassi)
+  - #3223 CLang, GMutexLocker: error: unused variable 'locker'
+    [-Werror,-Wunused-variable]
+  - #3225 2.79 regression: gdatetime test failing on 64-bit big-endian since
+    #3119
+  - #3226 resource test fails on Debian mips64el: test5.gresource is not linked
+    but the test assumes it should be (Simon McVittie)
+  - !3774 [th/g-object-priv] add private data to GObject and use per-object
+    locking
+  - !3780 girepository: Use standard types instead of glib specific
+  - !3789 gdatetime: Fix title of documentation comment
+  - !3792 build: Tell gi-docgen where to find the GIR files
+  - !3793 Shorten the title for D-Bus interface docs
+  - !3794 Add boxed GType for GRand
+  - !3795 girepository: Skip GIRepository versions not matching GIRepository-3.0
+  - !3798 docs: Drop outdated .gitignore files
+  - !3799 tests: Fix a minor leak in the new GParamSpecPool test
+  - !3800 ci: Re-enable and fix FreeBSD CI
+  - !3801 gmessages: Port all doc comments to gi-docgen
+  - !3802 [th/g-pointer-bit-lock-ext] glib: add g_pointer_bit_unlock_and_set()
+    and g_pointer_bit_lock_mask_ptr()
+  - !3803 ci: Fix tarballing the docs on dist
+  - !3805 girepository: Various small API cleanups
+  - !3806 gsignal.c: drop an optimization that is undefined behaviour
+  - !3808 glib/deprecated: Skip all the deprecated gthread api
+  - !3809 docs: Fix links to symbols outside the allowed namsepace
+  - !3810 gstrfuncs: Improve and port g_set_str() docs to gi-docgen
+  - !3811 gvariant-parser: Mention annotated types
+  - !3812 brz.c: Use uintptr_t instead of a hardcoded list of 64-bit arches
+  - !3813 gobject: define HAVE_OPTIONAL_FLAGS for sizeof(void*) > 8
+  - !3814 Fix typo in GPOINTER_TO_SIZE documentation
+  - !3817 docs: Allow building man pages without the reference documentation
+  - !3818 docs: Clarify >=2.76 changes to g_module_open()
+  - !3821 tests: Fix a minor leak in the socket test
+  - !3823 girepository: Misc cleanups
+  - !3826 genums: use g_once_init_enter_pointer for GType initializers
+  - !3827 array-test: Don't assume sizeof(void*)==sizeof(gsize)
+  - !3831 gvariant-core: Don’t call posix_memalign() with size==0
+  - !3833 girepository: Change various alignments to use size_t
+  - !3835 build: Ignore branches in g_clear_*() functions under lcov
+  - !3837 tests: A couple of test isolation improvements
+  - !3839 gvarianttype: Fix typos
+  - !3840 girepository: Exclude private symbols from the ABI
+  - !3841 docs: Fix member names of GLib.LogLevelFlags
+  - !3842 gio, gmodule, gthread: compile windows resources only in shared build
+
+* Translation updates:
+  - Georgian (Ekaterine Papava)
+  - Russian (Artur S0)
+
+
+Overview of changes in GLib 2.79.0, 2023-12-22
+==============================================
+
+ * Port to gi-docgen and drop gtk-doc support — dependencies have changed, and
+   Meson needs `-Ddocumentation` now rather than `-Dgtk_doc` (#3037, work by
+   multiple people)
+
+ * Move libgirepository into glib.git from gobject-introspection.git — but tools
+   like `g-ir-scanner` are currently still in gobject-introspection.git. For the
+   moment, glib.git needs to be built twice, once with `-Dintrospection=false`,
+   then build gobject-introspection.git, then re-build glib.git with
+   `-Dintrospection=true`. This process will evolve throughout the GLib 2.80
+   cycle. The API and ABI of libgirepository has changed, and accordingly its
+   version number has been bumped from 1.0 to 2.0 (note: the version number of
+   `GIRepository-*.gir` has been bumped from 2.0 to 3.0; see !3786). The GIR and
+   typelib file formats have not been changed, and are still at version 1.0.
+   (#3155, work by multiple people)
+
+ * Match behaviour for `GAppInfo` searches has changed (#3082, work by Nelson
+   Benítez León)
+
+ * Rename `GTK_USE_PORTAL` environment variable to `GIO_USE_PORTALS` (#3107,
+   work by Philip Withnall)
+
+ * Bump Meson dependency to 1.2.0 and depend on Python `packaging` module
+   (!3666, !3752)
+
+Bugs fixed:
+  - #596 GApplication in Garbage Collected environments would benefit from a
+    g_application_command_line_exit() to enable remote instances to exit.
+    (Aleksandr Mezin)
+  - #791 Wish: Add a "nodelay" property to GSocket or GTcpConnection (Philip
+    Withnall)
+  - #2810 thread-pool-slow intermittent assertion failure in
+    test_thread_sort_entry_func() (Philip Withnall)
+  - #2824 G_REGEX_OPTIMIZE causes incorrect regex behaviour
+  - #2991 Drop translatable pspec nick/blurbs from properties in GIO (Sophie
+    Herold)
+  - #3082 Investigate prioritising prefix matches on GAppInfo keywords over
+    substring matches on names (Nelson Benítez León)
+  - #3087 glib doesn't cleanly unload on Windows (Luca Bacci)
+  - #3098 Make invalid escape sequences in GKeyFile fatal (Philip Withnall)
+  - #3103 mkenums: Can't parse an enum value with value ',' (Lukáš Tyrychtr)
+  - #3105 NetworkManager 1.44.0 crashes repeatedly with glib 2.78.0 (Philip
+    Withnall)
+  - #3107 Rename GTK_USE_PORTAL to avoid portal services being run with portals
+    force-enabled (Philip Withnall)
+  - #3111 gsubprocess-testprog.c: build error with cygwin (sys/ptrace.h: No such
+    file or directory) (Philip Withnall)
+  - #3112 Update to Unicode 15.1 (Philip Withnall)
+  - #3115 Support for additional strftime formatting capabilities
+  - #3116 gio clears modification time in microseconds when setting with
+    `set_modification_date_time` (Lukáš Tyrychtr)
+  - #3119 Add support for `%Ey` to g_date_time_format() (Philip Withnall)
+  - #3120 Build of glib 2.78.0 ignores -Dlibelf=disabled (Philip Withnall)
+  - #3128 glib-2.78.0 fails at gio/tests/gsubprocess.p/gsubprocess.c.o
+  - #3130 Segfault when creating GIO GPropertyAction without properties
+  - #3134 glib incompatible with Python 3.12 due to distutils usage
+  - #3135 Add GNU/Hurd CI
+  - #3140 Add a flag to not copy modification time when copying files (Khalid
+    Abu Shawarib)
+  - #3144 `g_file_set_contents_full()` doesn't truncate the file (without
+    `G_FILE_SET_CONTENTS_CONSISTENT`) (Philip Withnall)
   - #3156 check for #ifdef PTRACE_O_EXITKILL will always fail since it isn't a
     macro (Alessandro Bono)
   - #3157 gsubprocess build-time test intermittently timing out since 2.78.1
     (Simon McVittie)
-  - !3673 Backport !3669 “meson: Improve PTRACE_O_EXITKILL presence check” to
+  - #3158 "CRITICAL" log when using --attributes option for "gio info" (Philip
-    glib-2-78
-  - !3680 Backport !3677 “Make GQuark register intentional leaks” to glib-2-78
-  - !3681 Backport 3678 “gsignalgroup: Avoid function call with side effect in
-    g_return_* macro” to glib-2-78
-  - !3686 Backport !3685 “tests: Don't assume that sh optimizes simple commands
-    into exec” to glib-2-78
-  - !3718 Backport !3714 “xdgmime: Handle buggy type definitions with circular
-    inheritance” to glib-2-78
-  - !3727 Backport !3725 “collate: Don't segfault on bad input” to glib-2-78
-
-* Translation updates:
-  - Ukrainian (Yuri Chornoivan)
-
-
-Overview of changes in GLib 2.78.1, 2023-10-25
-==============================================
-
-* Fix truncating files when `g_file_set_contents_full()` is called without
-  `G_FILE_SET_CONTENTS_CONSISTENT` (#3144, work by Philip Withnall)
-
-* Fix `-Dlibelf=disabled` on Linux (#3120, work by Philip Withnall)
-
-* Bugs fixed:
-  - #3105 NetworkManager 1.44.0 crashes repeatedly with glib 2.78.0 (Philip
     Withnall)
-  - #3111 gsubprocess-testprog.c: build error with cygwin (sys/ptrace.h: No such
+  - #3159 glib regex test fails JIT compiler tests under musl libc (Pablo Correa
-    file or directory) (Philip Withnall)
+    Gómez)
-  - #3116 gio clears modification time in microseconds when setting with
+  - #3161 codegen installation is broken
-    `set_modification_date_time` (Lukáš Tyrychtr)
+  - #3168 gvfs-udisks2-volume-monitor SIGSEGV in g_content_type_guess_for_tree()
-  - #3120 Build of glib 2.78.0 ignores -Dlibelf=disabled (Philip Withnall)
+    due to filename with bad encoding (Ondrej Holy)
-  - #3128 glib-2.78.0 fails at gio/tests/gsubprocess.p/gsubprocess.c.o
+  - #3183 g_dbus_connection_signal_subscribe with flag
-  - #3130 Segfault when creating GIO GPropertyAction without properties
+    G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_PATH doesn't work with an arg0 that is an
-  - #3144 `g_file_set_contents_full()` doesn't truncate the file (without
+    object path (Philip Withnall)
-    `G_FILE_SET_CONTENTS_CONSISTENT`) (Philip Withnall)
+  - #3185 g_utf8_collate_key() segfaults when passed an invalid length
+  - #3186 [RFE] Increase gio sniff buffer for mime type magic detection to 16K
+    or so (Philip Withnall)
+  - #3187 g_vasprintf crashes when passed invalid UTF-8 (Philip Withnall)
+  - #3191 Crash in __gio_xdg_cache_mime_type_subclass (Philip Withnall)
+  - #3203 Fdo notification fails without AppID (Michael Catanzaro)
+  - !3143 gatomic: Use g(u)intptr where appropriate
+  - !3316 gobject: Separate GWeakRef from GWeakNotify
+  - !3394 gsocketclient: Document delays/timeouts better
+  - !3457 glib-unix: Add convenience API for pipes
+  - !3524 add muslc ci
+  - !3552 gutils: Use international symbol for bits
+  - !3566 Update annotations for GAsyncQueue and GDir
+  - !3567 Update annotations for GHmac
+  - !3568 Update GOptionContext annotations
+  - !3569 Small fixes and cleanups for Vectored Exception Handlers
+  - !3571 Update GStringChunk annotations
+  - !3572 Update GRand annotations
+  - !3573 Update GTimer annotations
   - !3576 guniprop.c: Avoid creating (temporarily) out-of-bounds pointers
+  - !3577 gthread: introduce g_once_init_{enter,leave}_pointer
+  - !3578 GType: Use guintptr as the underlying storage if larger than gsize
   - !3579 Fixes for integer cast warnings when targeting CHERI
   - !3580 Fix test_find_program on FreeBSD
-  - !3589 gconstructor.h: Ensure [c|d]tor prototypes are present for MSVC (Chun-
+  - !3581 gthread: Fix optional/nullable annotations for g_once_init_*()
-    wei Fan)
+  - !3582 Buffer needs to be aligned correctly to receive linux_dirent64.
+  - !3589 gconstructor.h: Ensure [c|d]tor prototypes are present for MSVC
+    (Chun-wei Fan)
+  - !3590 gtestutils.h: Fix warning with -Wsign-conversion caused by
+    g_assert_cmpint
+  - !3591 Switch to using gi-docgen for docs (batch 1)
   - !3594 Fix gutils-user-database test on macOS
+  - !3595 gobject: cache flags needed for g_type_create_instance()
   - !3596 Add value annotation to G_TYPE_FUNDAMENTAL_MAX
+  - !3597 Expand security policy to cover previous stable branch
+  - !3598 Document NULL pointer pitfall in toolchain requirements
   - !3601 meson: Fix Windows build with PCRE2 as sibling subproject
-  - !3604 Backport !3589 “gconstructor.h: Ensure [c|d]tor prototypes are present
+  - !3603 Add GBytes variants for GSocket receive methods
-    for MSVC” to glib-2-78
+  - !3605 build: Post-release version bump
-  - !3608 Backport !3587 “glocalfileinfo: Preserve microseconds for
+  - !3607 Make sure the `GTask` is freed on a graceful disconnect
-    access/modify times” to glib-2-78
+  - !3610 gdesktopappinfo: Do not search Comment field
-  - !3609 Backport !3607 “Make sure the `GTask` is freed on a graceful
+  - !3611 tests/constructor: Fix "unknown pragma ignored" warning on clang
-    disconnect” to glib-2-78 (Pavel Sobolev)
+  - !3612 Update GStrv annotations
-  - !3614 Backport !3582 “Buffer needs to be aligned correctly to receive
+  - !3613 tests: Fix gdatetime test on non-UTC systems
-    linux_dirent64.” to glib-2-78
+  - !3620 gmain: avoid a GList traversal when removing source
-  - !3616 Backport !3590 “gtestutils.h: Fix warning with -Wsign-conversion
+  - !3621 wakeup: do single read when using eventfd()
-    caused by g_assert_cmpint” to glib-2-78
+  - !3623 Windows: Compile with the UNICODE / _UNICODE macros
-  - !3619 Backport !3617 “tests: Drop unnecessary include from gsubprocess-
+  - !3624 wakeup: Fix g_wakeup_acknowledge if signal comes in
-    testprog.c” to glib-2-78
+  - !3627 Add Hurd code owners
-  - !3622 Backport !3621 “wakeup: do single read when using eventfd()” to
+  - !3628 glib-unix: Use full path to gstdio.h include
-    glib-2-78
+  - !3629 glib/tests/meson.build: remove identical build targets
-  - !3625 Backport !3624 “wakeup: Fix g_wakeup_acknowledge if signal comes in”
+  - !3630 glib-compile-resources: ensure alignment is at least sizeof(void *)
-    to glib-2-78
+  - !3632 Stop using enums in bitfields
-  - !3644 Backport !3633 “Use g_task_return in task threads” to glib-2-78
+  - !3633 Use g_task_return in task threads
-  - !3649 Backport !3648 “build: Fix -Dlibelf=disabled on Linux” to glib-2-78
+  - !3634 Switch to using gi-docgen for docs (batch 2)
-  - !3659 Backport !3650 “gfileutils: Add a missing ftruncate() call when
+  - !3635 Fix warnings with Clang on Windows and enable --Werror in CI
-    writing files” to glib-2-78
+  - !3636 Generate introspection data
+  - !3637 gstrvbuilder: Add g_strv_builder_take
+  - !3638 Cleanup and add content to glib debugging using gdb scripts
+  - !3640 GIO/tests: skip test_resources_binary on MIPS platforms
+  - !3641 build: Simplify MIPS test check
+  - !3645 Switch to using gi-docgen for docs (batch 3)
+  - !3646 ci: Update from clang-format-11 to clang-format-14
+  - !3647 Switch to using gi-docgen for docs (batch 4)
+  - !3652 GApplicationCommandLine: add print[err]_literal()
+  - !3654 gdatetime: Fix minor leaks from strup/strdown calls
+  - !3655 gdatetime: Fix incorrect alt-digits being used after changing locale
+  - !3656 gmodule-dl: Use RTLD_DEFAULT on FreeBSD too
+  - !3660 Switch to using gi-docgen for docs (batch 5)
+  - !3661 Switch to using gi-docgen for docs (batch 6)
+  - !3662 Switch to using gi-docgen for docs (batch 7)
+  - !3663 gdbusconnection: don't cache G_IO_ERROR_CANCELLED errors
+  - !3664 gmain: optimize "context->sources" hash table to use as set
+  - !3665 ci: Remove .build-linux from Hurd CI scheduled job
+  - !3666 build: Bump Meson dependency to 1.2.0
+  - !3667 Switch to using gi-docgen for docs (batch 8)
+  - !3668 Socket & readiness fixes
+  - !3671 gio/tests: Add test generated txt as the resources test dependency
+  - !3672 glib-private: Check for LSAN support at runtime when controlling it
+  - !3674 gtask: Add g_task_return_prefixed_error()
+  - !3677 Make GQuark register intentional leaks
+  - !3678 gsignalgroup: Avoid function call with side effect in g_return_* macro
+  - !3679 gmessages: fix dropping irrelevant log domains
+  - !3682 tests: Fix dependency of test.gresource on test-generated.txt
+  - !3683 glib: Disable dynamic asan loading on macOS
+  - !3687 fix: about libproc.h and PROC_PIDLISTFD_SIZE
+  - !3688 build: Fix the inclusion paths for GIR files in gi-docgen
+  - !3689 meson: Add missing dependencies for utility files for gdbus-codegen
+  - !3690 Switch to using gi-docgen for docs (batch 9)
+  - !3695 gvalue: add "steal_string"
+  - !3699 [th/prgname] use atomic pointers for g_prgname/g_application_name and
+    add g_set_prgname_once()
+  - !3701 tests: Fix gio-tool.py test on macOS
+  - !3702 glib.supp: Suppress the global_mime_dirs allocations
+  - !3703 Port GIRepository to GTypeInstance and add introspection
+  - !3704 girepository: Rename symbols to the GI namespace
+  - !3707 girepository: Ignore set-but-not-used warnings with G_DISABLE_ASSERT
+  - !3708 Fix various leaks in cmph-bdz-test and gutils
+  - !3709 Switch to using gi-docgen for docs (batch 10)
+  - !3710 gmessages: introduce g_log_writer_default_set_debug_domains()
+  - !3711 ghmac: Add a boxed type for GHmac and fix introspection build
+    accordingly
+  - !3712 Switch to using gi-docgen for docs (batch 11)
+  - !3713 gfileutils: Fix g_file_get_contents() silent under-read of large files
+    when off_t is wider than size_t
+  - !3714 xdgmime: Handle buggy type definitions with circular inheritance
+  - !3715 goption: Fix a typo
+  - !3716 tests: Improve build of cmph tests in girepository
+  - !3717 tests: provide reason for disabling convert test under musl
+  - !3721 gtestutils: Add g_test_trap_subprocess_with_envp() for testing envs
+  - !3722 gdir, gstrvbuilder: Add refcounting support and a boxed type
+  - !3723 gwin32: Un-hide symbols when building GIR
+  - !3726 tests: Fix fileutils build on FreeBSD and macOS
+  - !3731 tests: Fix string test failure on BSDs
+  - !3732 gspawn: Stop spewing debug messages
+  - !3733 ci: Make the Alpine CI name more consistent
+  - !3734 gdatetime: Disable ERA support on platforms which don’t support this
+  - !3735 ci: Fix printing info message at end of run-style-check-diff.sh
+  - !3736 build: Rename -Dgtk_doc option to -Ddocumentation and fix some
+    g-ir-scanner warnings
+  - !3739 Documentation only: Added clarification about GWeakNotify and removed
+    ambiguous text
+  - !3741 hash: Explicitly annotate key in iter_next as nullable
+  - !3743 ci: Install correct version of Meson on Alpine CI image
+  - !3745 tests: Assert there no errors first in gdbus-test-codegen
+  - !3751 Fix generated RST anchors for methods, signals and properties
+  - !3752 build: Make packaging module required
+  - !3753 gobject_gdb.py: Do not break bt on optimized build
+  - !3755 tests: Use textwrap.dedent to indent expected strings pleasingly
+  - !3757 ci: Re-add explicit Meson version to Alpine CI image
+  - !3758 docs: Add a section on version checking macros
+  - !3760 girepository: Various API cleanups
+  - !3761 gerror: Fix an old allow-none annotation
+  - !3762 [th/notify-queue] some optimization around
+    g_object_freeze_notify()/g_object_thaw_notify()
+  - !3763 girepository: Drop libgio dependency from gdump.c
+  - !3764 gsignal: fix reference to signals documentation page
+  - !3765 gapplication: Fix minor typo in docs
+  - !3767 girepository: Port documentation to gi-docgen and update
+  - !3768 ci: Build docs artifacts for deployment to docs.gtk.org
+  - !3770 GDateTime: Add usec precision API for unix time
+  - !3771 gtask: Add g_task_return_new_error_literal()
+  - !3772 gobject: Make GLib-2.0 gir build depend on GObject dependency
+  - !3773 girepository: Return enumerated versions and search paths as a GStrv
+  - !3776 glocalvfs: Remove unnecessary and buggy code
+  - !3777 Fix detecting size_t size when `-Wmissing-prototypes` is in CFLAGS
+  - !3779 gtypemodule: Add assertions in finalize()
+  - !3782 docs: fix a typo
+  - !3786 girepository: Re-number GIR file from 2.0 to 3.0
+  - !3787 docs: Install the gi-docgen docs
 
 * Translation updates:
   - Catalan (Jordi Mas i Hernandez)
@@ -87,15 +520,15 @@ Overview of changes in GLib 2.78.1, 2023-10-25
   - Czech (Daniel Rusek)
   - Esperanto (Kristjan SCHMIDT)
   - French (Alexandre Franke)
-  - Georgian (Ekaterine Papava)
   - Italian (Milo Casagrande)
   - Latvian (Rūdolfs Mazurs)
   - Portuguese (Brazil) (Rafael Fontenelle)
-  - Romanian (Daniel Șerbănescu)
+  - Romanian (Florentina Mușat)
   - Russian (Artur S0)
   - Slovenian (Matej Urbančič)
   - Spanish (Daniel Mustieles)
   - Turkish (Sabri Ünal)
+  - Ukrainian (Yuri Chornoivan)
 
 
 Overview of changes in GLib 2.78.0, 2023-09-08

README.md

@@ -19,9 +19,10 @@ GLib on Windows.
 
 ## Supported versions
 
-Only the most recent unstable and stable release series are supported. All
+Upstream GLib only supports the most recent stable release series, the previous
-older versions are not supported upstream and may contain bugs, some of
+stable release series, and the current development release series. All
-which may be exploitable security vulnerabilities.
+older versions are not supported upstream and may contain bugs, some of which
+may be exploitable security vulnerabilities.
 
 See [SECURITY.md](SECURITY.md) for more details.
 

SECURITY.md

@@ -7,11 +7,16 @@
 
 ## Supported Versions
 
-Upstream GLib only supports the most recent stable release series, and the
+Upstream GLib only supports the most recent stable release series, the previous
-current development release series. Any older stable release series are no
+stable release series, and the current development release series. Any older
-longer supported, although they may still receive backported security updates
+stable release series are no longer supported, although they may still receive
-in long-term support distributions. Such support is up to the distributions,
+backported security updates in long-term support distributions. Such support is
-though.
+up to the distributions, though.
+
+The previous stable release series will generally receive fixes only for high
+impact security issues, at maintainer discretion. Since such issues are rare,
+it's expected that there may be no backports or releases on the previous stable
+branch.
 
 Under GLib’s versioning scheme, stable release series have an *even* minor
 component (for example, 2.66.0, 2.66.1, 2.68.3), and development release series

docs/CODEOWNERS

@@ -53,6 +53,9 @@ subprojects/		@xclaesse @nirbheek @pwithnall
 *bsd*		@jmatthew @ajacoutot @lantw @pwithnall
 *kqueue*	@jmatthew @ajacoutot @lantw @pwithnall
 
+# GNU Hurd support
+*hurd*	@bugaevc @sthibaul
+
 # flatpak portals
 gio/*portal*	@matthiasc @alexl @pwithnall
 

docs/reference/.gitignore

@@ -1,16 +0,0 @@
-*-decl-list.txt
-*-decl.txt
-*-unused.txt
-*-undocumented.txt
-*-undeclared.txt
-*.args
-*.hierarchy
-*.interfaces
-*.prerequisites
-*.signals
-*.stamp
-html
-xml
-*.bak
-version.xml
-*.1

docs/reference/gio/.gitignore

@@ -1,3 +0,0 @@
-*.1
-gio-overrides.txt
-tmpl

docs/reference/gio/concat-files-helper.py

@@ -1,36 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
-# Copyright (C) 2018 Collabora Inc.
-#
-# This library is free software; you can redistribute it and/or
-# modify it under the terms of the GNU Lesser General Public
-# License as published by the Free Software Foundation; either
-# version 2.1 of the License, or (at your option) any later version.
-#
-# This library is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-# Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General
-# Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
-#
-# Author: Xavier Claessens <xavier.claessens@collabora.com>
-
-import os
-import sys
-
-if len(sys.argv) < 3:
-    print(
-        "Usage: {} <output file> <input file 1> ...".format(
-            os.path.basename(sys.argv[0])
-        )
-    )
-    sys.exit(1)
-
-with open(sys.argv[1], "w") as outfile:
-    for fname in sys.argv[2:]:
-        with open(fname) as infile:
-            for line in infile:
-                outfile.write(line)

docs/reference/gio/dbus-error.md

@@ -0,0 +1,79 @@
+Title: D-Bus Error Handling
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 2010 David Zeuthen
+SPDX-FileCopyrightText: 2012 Aleksander Morgado
+
+# D-Bus Error Handling
+
+All facilities that return errors from remote methods (such as
+[method@Gio.DBusConnection.call_sync]) use [type@GLib.Error] to represent both
+D-Bus errors (e.g. errors returned from the other peer) and locally in-process
+generated errors.
+
+To check if a returned [type@GLib.Error] is an error from a remote peer, use
+[func@Gio.DBusError.is_remote_error]. To get the actual D-Bus error name,
+use [func@Gio.DBusError.get_remote_error]. Before presenting an error, always
+use [func@Gio.DBusError.strip_remote_error].
+
+In addition, facilities used to return errors to a remote peer also use 
+[type@GLib.Error]. See [method@Gio.DBusMethodInvocation.return_error] for
+discussion about how the D-Bus error name is set.
+
+Applications can associate a [type@GLib.Error] error domain with a set of D-Bus
+errors in order to automatically map from D-Bus errors to [type@GLib.Error] and
+back. This is typically done in the function returning the [type@GLib.Quark] for
+the error domain:
+
+```c
+// foo-bar-error.h:
+
+#define FOO_BAR_ERROR (foo_bar_error_quark ())
+GQuark foo_bar_error_quark (void);
+
+typedef enum
+{
+  FOO_BAR_ERROR_FAILED,
+  FOO_BAR_ERROR_ANOTHER_ERROR,
+  FOO_BAR_ERROR_SOME_THIRD_ERROR,
+  FOO_BAR_N_ERRORS / *< skip >* /
+} FooBarError;
+
+// foo-bar-error.c:
+
+static const GDBusErrorEntry foo_bar_error_entries[] =
+{
+  {FOO_BAR_ERROR_FAILED,           "org.project.Foo.Bar.Error.Failed"},
+  {FOO_BAR_ERROR_ANOTHER_ERROR,    "org.project.Foo.Bar.Error.AnotherError"},
+  {FOO_BAR_ERROR_SOME_THIRD_ERROR, "org.project.Foo.Bar.Error.SomeThirdError"},
+};
+
+// Ensure that every error code has an associated D-Bus error name
+G_STATIC_ASSERT (G_N_ELEMENTS (foo_bar_error_entries) == FOO_BAR_N_ERRORS);
+
+GQuark
+foo_bar_error_quark (void)
+{
+  static gsize quark = 0;
+  g_dbus_error_register_error_domain ("foo-bar-error-quark",
+                                      &quark,
+                                      foo_bar_error_entries,
+                                      G_N_ELEMENTS (foo_bar_error_entries));
+  return (GQuark) quark;
+}
+```
+
+With this setup, a D-Bus peer can transparently pass e.g.
+`FOO_BAR_ERROR_ANOTHER_ERROR` and other peers will see the D-Bus error name
+`org.project.Foo.Bar.Error.AnotherError`.
+
+If the other peer is using GDBus, and has registered the association with
+[func@Gio.DBusError.register_error_domain] in advance (e.g. by invoking the
+`FOO_BAR_ERROR` quark generation itself in the previous example) the peer will
+see also `FOO_BAR_ERROR_ANOTHER_ERROR` instead of `G_IO_ERROR_DBUS_ERROR`. Note
+that GDBus clients can still recover `org.project.Foo.Bar.Error.AnotherError`
+using [func@Gio.DBusError.get_remote_error].
+
+Note that the `G_DBUS_ERROR` error domain is intended only for returning errors
+from a remote message bus process. Errors generated locally in-process by e.g.
+[class@Gio.DBusConnection] should use the `G_IO_ERROR` domain.
+

docs/reference/gio/dbus-introspection.md

@@ -0,0 +1,23 @@
+Title: D-Bus Introspection Data
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 2010 David Zeuthen
+SPDX-FileCopyrightText: 2010 Matthias Clasen
+
+# D-Bus Introspection Data
+
+Various data structures and convenience routines to parse and
+generate D-Bus introspection XML. Introspection information is
+used when registering objects with [method@Gio.DBusConnection.register_object].
+
+The format of D-Bus introspection XML is specified in the
+[D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format).
+
+The main introspection data structures are:
+ * [type@Gio.DBusNodeInfo]
+ * [type@Gio.DBusInterfaceInfo]
+ * [type@Gio.DBusPropertyInfo]
+ * [type@Gio.DBusMethodInfo]
+ * [type@Gio.DBusSignalInfo]
+ * [type@Gio.DBusArgInfo]
+ * [type@Gio.DBusAnnotationInfo]
+

docs/reference/gio/dbus-name-owning.md

@@ -0,0 +1,14 @@
+Title: D-Bus Name Owning
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 2010 David Zeuthen
+
+# D-Bus Name Owning
+
+Convenience API for owning bus names.
+
+A simple example for owning a name can be found in
+[`gdbus-example-own-name.c`](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-own-name.c).
+
+The main API for owning names is:
+ * [func@Gio.bus_own_name]
+ * [func@Gio.bus_unown_name]

docs/reference/gio/dbus-name-watching.md

@@ -0,0 +1,14 @@
+Title: D-Bus Name Watching
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 2010 David Zeuthen
+
+# D-Bus Name Watching
+
+Convenience API for watching bus names.
+
+A simple example for watching a name can be found in
+[`gdbus-example-watch-name.c`](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-watch-name.c).
+
+The main API for watching names is:
+ * [func@Gio.bus_watch_name]
+ * [func@Gio.bus_unwatch_name]

docs/reference/gio/dbus-utils.md

@@ -0,0 +1,28 @@
+Title: D-Bus Utilities
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 2010 David Zeuthen
+
+# D-Bus Utilities
+
+Various utility routines related to D-Bus.
+
+GUID support:
+ * [func@Gio.dbus_is_guid]
+ * [func@Gio.dbus_generate_guid]
+
+Name validation:
+ * [func@Gio.dbus_is_name]
+ * [func@Gio.dbus_is_unique_name]
+ * [func@Gio.dbus_is_member_name]
+ * [func@Gio.dbus_is_interface_name]
+ * [func@Gio.dbus_is_error_name]
+
+Conversion between [type@GLib.Variant] and [type@GObject.Value]:
+ * [func@Gio.dbus_gvariant_to_gvalue]
+ * [func@Gio.dbus_gvalue_to_gvariant]
+
+Path escaping:
+ * [func@Gio.dbus_escape_object_path_bytestring]
+ * [func@Gio.dbus_escape_object_path]
+ * [func@Gio.dbus_unescape_object_path]
+

docs/reference/gio/error.md

@@ -0,0 +1,12 @@
+Title: GIOError
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 2007 A. Walton
+
+# GIOError
+
+Contains helper functions for reporting errors to the user.
+
+Functions for converting between different error reporting mechanisms:
+ * [func@Gio.io_error_from_errno]
+ * [func@Gio.io_error_from_file_error]
+

docs/reference/gio/file-attributes.md

@@ -0,0 +1,111 @@
+Title: File Attributes
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 2007 Andrew Walton
+SPDX-FileCopyrightText: 2007 Alexander Larsson
+SPDX-FileCopyrightText: 2008, 2014 Matthias Clasen
+SPDX-FileCopyrightText: 2011 Murray Cumming
+SPDX-FileCopyrightText: 2012 David King
+
+# File Attributes
+
+File attributes in GIO consist of a list of key-value pairs.
+
+Keys are strings that contain a key namespace and a key name, separated
+by a colon, e.g. `namespace::keyname`. Namespaces are included to sort
+key-value pairs by namespaces for relevance. Keys can be retrieved
+using wildcards, e.g. `standard::*` will return all of the keys in the
+`standard` namespace.
+
+The list of possible attributes for a filesystem (pointed to by a
+[iface@Gio.File]) is available as a [struct@Gio.FileAttributeInfoList]. This
+list is queryable by key names as indicated earlier.
+
+Information is stored within the list in [struct@Gio.FileAttributeInfo]
+structures. The info structure can store different types, listed in the enum
+[type@Gio.FileAttributeType]. Upon creation of a [struct@Gio.FileAttributeInfo],
+the type will be set to `G_FILE_ATTRIBUTE_TYPE_INVALID`.
+
+Classes that implement [iface@Gio.File] will create a
+[struct@Gio.FileAttributeInfoList] and install default keys and values for their
+given file system, architecture, and other possible implementation details
+(e.g., on a UNIX system, a file attribute key will be registered for the user ID
+for a given file).
+
+## Default Namespaces
+
+- `"standard"`: The ‘Standard’ namespace. General file information that
+  any application may need should be put in this namespace. Examples
+  include the file’s name, type, and size.
+- `"etag`: The [Entity Tag](gfile.html#entity-tags) namespace. Currently, the
+  only key in this namespace is `value`, which contains the value of the current
+  entity tag.
+- `"id"`: The ‘Identification’ namespace. This namespace is used by file
+  managers and applications that list directories to check for loops and
+  to uniquely identify files.
+- `"access"`: The ‘Access’ namespace. Used to check if a user has the
+  proper privileges to access files and perform file operations. Keys in
+  this namespace are made to be generic and easily understood, e.g. the
+  `can_read` key is true if the current user has permission to read the
+  file. UNIX permissions and NTFS ACLs in Windows should be mapped to
+  these values.
+- `"mountable"`: The ‘Mountable’ namespace. Includes simple boolean keys
+  for checking if a file or path supports mount operations, e.g. mount,
+  unmount, eject. These are used for files of type `G_FILE_TYPE_MOUNTABLE`.
+- `"time"`: The ‘Time’ namespace. Includes file access, changed, created
+  times.
+- `"unix"`: The ‘Unix’ namespace. Includes UNIX-specific information and
+  may not be available for all files. Examples include the UNIX UID,
+  GID, etc.
+- `"dos"`: The ‘DOS’ namespace. Includes DOS-specific information and may
+  not be available for all files. Examples include `is_system` for checking
+  if a file is marked as a system file, and `is_archive` for checking if a
+  file is marked as an archive file.
+- `"owner"`: The ‘Owner’ namespace. Includes information about who owns a
+  file. May not be available for all file systems. Examples include `user`
+  for getting the user name of the file owner. This information is often
+  mapped from some backend specific data such as a UNIX UID.
+- `"thumbnail"`: The ‘Thumbnail’ namespace. Includes information about file
+  thumbnails and their location within the file system. Examples of keys in
+  this namespace include `path` to get the location of a thumbnail, `failed`
+  to check if thumbnailing of the file failed, and `is-valid` to check if
+  the thumbnail is outdated.
+- `"filesystem"`: The ‘Filesystem’ namespace. Gets information about the
+  file system where a file is located, such as its type, how much space is
+  left available, and the overall size of the file system.
+- `"gvfs"`: The ‘GVFS’ namespace. Keys in this namespace contain information
+  about the current GVFS backend in use.
+- `"xattr"`: The ‘xattr’ namespace. Gets information about extended user
+  attributes. See [`attr(5)`](man:attr(5)). The `user.` prefix of the extended
+  user attribute name is stripped away when constructing keys in this namespace,
+  e.g. `xattr::mime_type` for the extended attribute with the name
+  `user.mime_type`. Note that this information is only available if
+  GLib has been built with extended attribute support.
+- `"xattr-sys"`: The ‘xattr-sys’ namespace. Gets information about
+  extended attributes which are not user-specific. See [`attr(5)`](man:attr(5)).
+  Note that this information is only available if GLib has been built with
+  extended attribute support.
+- `"selinux"`: The ‘SELinux’ namespace. Includes information about the
+  SELinux context of files. Note that this information is only available
+  if GLib has been built with SELinux support.
+
+Please note that these are not all of the possible namespaces.
+More namespaces can be added from GIO modules or by individual applications.
+For more information about writing GIO modules, see [class@Gio.IOModule].
+
+<!-- TODO: Implementation note about using extended attributes on supported
+file systems -->
+
+## Default Keys
+
+For a list of the built-in keys and their types, see the [class@Gio.FileInfo]
+documentation.
+
+Note that there are no predefined keys in the `xattr` and `xattr-sys`
+namespaces. Keys for the `xattr` namespace are constructed by stripping
+away the `user.` prefix from the extended user attribute, and prepending
+`xattr::`. Keys for the `xattr-sys` namespace are constructed by
+concatenating `xattr-sys::` with the extended attribute name. All extended
+attribute values are returned as hex-encoded strings in which bytes outside
+the ASCII range are encoded as escape sequences of the form `\xnn`
+where `nn` is a 2-digit hexadecimal number.
+

docs/reference/gio/gapplication.rst

@@ -0,0 +1,195 @@
+.. _gapplication(1):
+.. meta::
+   :copyright: Copyright 2013 Allison Karlitskaya
+   :license: LGPL-2.1-or-later
+..
+   This has to be duplicated from above to make it machine-readable by `reuse`:
+   SPDX-FileCopyrightText: 2013 Allison Karlitskaya
+   SPDX-License-Identifier: LGPL-2.1-or-later
+
+============
+gapplication
+============
+
+--------------------------
+D-Bus application launcher
+--------------------------
+
+SYNOPSIS
+--------
+
+|  **gapplication** help [COMMAND]
+|  **gapplication** version
+|  **gapplication** list-apps
+|  **gapplication** launch <APP-ID>
+|  **gapplication** launch <APP-ID> [FILE…]
+|  **gapplication** list-actions <APP-ID>
+|  **gapplication** action <APP-ID> <ACTION> [PARAMETER]
+
+DESCRIPTION
+-----------
+
+``gapplication`` is a commandline implementation of the client-side of the
+``org.freedesktop.Application`` interface as specified by the freedesktop.org
+Desktop Entry Specification.
+
+``gapplication`` can be used to start applications that have ``DBusActivatable``
+set to ``true`` in their ``.desktop`` files and can be used to send messages to
+already-running instances of other applications.
+
+It is possible for applications to refer to ``gapplication`` in the ``Exec``
+line of their ``.desktop`` file to maintain backwards compatibility with
+implementations that do not directly support ``DBusActivatable``.
+
+``gapplication`` ships as part of GLib.
+
+COMMANDS
+--------
+
+``help [COMMAND]``
+
+  Displays a short synopsis of the available commands or provides detailed help
+  on a specific command.
+
+``version``
+
+  Prints the GLib version whence ``gapplication`` came.
+
+``list-apps``
+
+  Prints a list of all application IDs that are known to support D-Bus
+  activation.  This list is generated by scanning ``.desktop`` files as per the
+  current ``XDG_DATA_DIRS``.
+
+``launch <APP-ID> [FILE…]``
+
+  Launches an application.
+
+  The first parameter is the application ID in the familiar ‘reverse DNS’ style
+  (e.g. ``org.gnome.app``) without the ``.desktop`` suffix.
+
+  Optionally, if additional parameters are given, they are treated as the names
+  of files to open and may be filenames or URIs.  If no files are given then the
+  application is simply activated.
+
+``list-actions <APP-ID>``
+
+  List the actions declared in the application’s ``.desktop`` file.  The
+  parameter is the application ID, as above.
+
+``action <APP-ID> <ACTION> [PARAMETER]``
+
+  Invokes the named action (in the same way as would occur when activating an
+  action specified in the ``.desktop`` file).
+
+  The application ID (as above) is the first parameter.  The action name
+  follows.
+
+  Optionally, following the action name can be one parameter, in GVariant
+  format, given as a single argument.  Make sure to use sufficient quoting.
+
+EXAMPLES
+--------
+
+From the commandline
+^^^^^^^^^^^^^^^^^^^^
+
+Launching an application::
+
+   gapplication launch org.example.fooview
+
+Opening a file with an application::
+
+   gapplication launch org.example.fooview ~/file.foo
+
+Opening many files with an application::
+
+   gapplication launch org.example.fooview ~/foos/*.foo
+
+Invoking an action on an application::
+
+   gapplication action org.example.fooview create
+
+Invoking an action on an application, with an action::
+
+   gapplication action org.example.fooview show-item '"item_id_828739"'
+
+From the ``Exec`` lines of a ``.desktop`` file
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The commandline interface of ``gapplication`` was designed so that it could be
+used directly from the ``Exec`` line of a ``.desktop`` file.
+
+You might want to do this to allow for backwards compatibility with
+implementations of the specification that do not understand how to do D-Bus
+activation, without having to install a separate utility program.
+
+Consider the following example::
+
+   [Desktop Entry]
+   Version=1.1
+   Type=Application
+   Name=Foo Viewer
+   DBusActivatable=true
+   MimeType=image/x-foo;
+   Exec=gapplication launch org.example.fooview %F
+   Actions=gallery;create;
+
+   [Desktop Action gallery]
+   Name=Browse Gallery
+   Exec=gapplication action org.example.fooview gallery
+
+   [Desktop Action create]
+   Name=Create a new Foo!
+   Exec=gapplication action org.example.fooview create
+
+From a script
+^^^^^^^^^^^^^
+
+If installing an application that supports D-Bus activation you may still want
+to put a file in ``/usr/bin`` so that your program can be started from a
+terminal.
+
+It is possible for this file to be a shell script.  The script can handle
+arguments such as ``--help`` and ``--version`` directly.  It can also parse
+other command line arguments and convert them to uses of ``gapplication`` to
+activate the application, open files, or invoke actions.
+
+Here is a simplified example, as may be installed in ``/usr/bin/fooview``::
+
+   #!/bin/sh
+
+   case "$1" in
+     --help)
+       echo "see ‘man fooview’ for more information"
+       ;;
+
+     --version)
+       echo "fooview 1.2"
+       ;;
+
+     --gallery)
+       gapplication action org.example.fooview gallery
+       ;;
+
+     --create)
+       gapplication action org.example.fooview create
+       ;;
+
+     -*)
+       echo "unrecognised commandline argument"
+       exit 1
+       ;;
+
+     *)
+       gapplication launch org.example.fooview "$@"
+       ;;
+   esac
+
+SEE ALSO
+--------
+
+`Desktop Entry Specification <https://specifications.freedesktop.org/desktop-entry-spec/latest/>`_,
+`gdbus(1) <man:gdbus(1)>`_,
+`xdg-open(1) <man:xdg-open(1)>`_,
+`desktop-file-validate(1) <man:desktop-file-validate(1)>`_

docs/reference/gio/gapplication.xml

@@ -1,352 +0,0 @@
-<refentry id="gapplication-tool" lang="en">
-  <refentryinfo>
-    <title>gapplication</title>
-    <productname>GIO</productname>
-    <authorgroup>
-      <author>
-        <contrib>Developer</contrib>
-        <firstname>Ryan</firstname>
-        <surname>Lortie</surname>
-      </author>
-    </authorgroup>
-  </refentryinfo>
-
-  <refmeta>
-    <refentrytitle>gapplication</refentrytitle>
-    <manvolnum>1</manvolnum>
-    <refmiscinfo class="manual">User Commands</refmiscinfo>
-  </refmeta>
-
-  <refnamediv>
-    <refname>gapplication</refname>
-    <refpurpose>D-Bus application launcher</refpurpose>
-  </refnamediv>
-
-  <refsynopsisdiv>
-    <cmdsynopsis>
-      <command>gapplication</command>
-      <arg choice="plain">help</arg>
-      <arg choice="opt"><replaceable>COMMAND</replaceable></arg>
-    </cmdsynopsis>
-    <cmdsynopsis>
-      <command>gapplication</command>
-      <arg choice="plain">version</arg>
-    </cmdsynopsis>
-    <cmdsynopsis>
-      <command>gapplication</command>
-      <arg choice="plain">list-apps</arg>
-    </cmdsynopsis>
-    <cmdsynopsis>
-      <command>gapplication</command>
-      <arg choice="plain">launch</arg>
-      <arg choice="plain"><replaceable>APPID</replaceable></arg>
-    </cmdsynopsis>
-    <cmdsynopsis>
-      <command>gapplication</command>
-      <arg choice="plain">launch</arg>
-      <arg choice="plain"><replaceable>APPID</replaceable></arg>
-      <arg choice="opt" rep="repeat"><replaceable>FILE</replaceable></arg>
-    </cmdsynopsis>
-    <cmdsynopsis>
-      <command>gapplication</command>
-      <arg choice="plain">list-actions</arg>
-      <arg choice="plain"><replaceable>APPID</replaceable></arg>
-    </cmdsynopsis>
-    <cmdsynopsis>
-      <command>gapplication</command>
-      <arg choice="plain">action</arg>
-      <arg choice="plain"><replaceable>APPID</replaceable></arg>
-      <arg choice="plain"><replaceable>ACTION</replaceable></arg>
-      <arg choice="opt"><replaceable>PARAMETER</replaceable></arg>
-    </cmdsynopsis>
-  </refsynopsisdiv>
-
-  <refsect1>
-    <title>Description</title>
-
-    <para>
-      <command>gapplication</command> is a commandline implementation of the client-side of the
-      <interfacename>org.freedesktop.Application</interfacename> interface as specified by the freedesktop.org
-      Desktop Entry Specification.
-    </para>
-
-    <para>
-      <command>gapplication</command> can be used to start applications that have
-      <varname>DBusActivatable</varname> set to <literal>true</literal> in their <filename>.desktop</filename>
-      files and can be used to send messages to already-running instances of other applications.
-    </para>
-
-    <para>
-      It is possible for applications to refer to <command>gapplication</command> in the <varname>Exec</varname>
-      line of their <filename class='extension'>.desktop</filename> file to maintain backwards compatibility
-      with implementations that do not directly support <varname>DBusActivatable</varname>.
-    </para>
-
-    <para>
-      <command>gapplication</command> ships as part of <application>GLib</application>.
-    </para>
-  </refsect1>
-
-  <refsect1>
-    <title>Commands</title>
-
-    <refsect2>
-      <title>Global commands</title>
-
-      <variablelist>
-        <varlistentry>
-          <term>
-            <command>help</command>
-            <arg choice="opt"><replaceable>COMMAND</replaceable></arg>
-          </term>
-          <listitem>
-            <para>
-              Displays a short synopsis of the available commands or provides detailed help on a specific
-              command.
-            </para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term>
-            <command>version</command>
-          </term>
-          <listitem>
-            <para>
-              Prints the GLib version whence <command>gapplication</command> came.
-            </para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term>
-            <command>list-apps</command>
-          </term>
-          <listitem>
-            <para>
-              Prints a list of all application IDs that are known to support D-Bus activation.  This list is
-              generated by scanning <filename class='extension'>.desktop</filename> files as per the current
-              <envar>XDG_DATA_DIRS</envar>.
-            </para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term>
-            <command>launch</command>
-            <arg choice="plain"><replaceable>APPID</replaceable></arg>
-            <arg choice="opt" rep="repeat"><replaceable>FILE</replaceable></arg>
-          </term>
-          <listitem>
-            <para>
-              Launches an application.
-            </para>
-            <para> 
-              The first parameter is the application ID in the familiar "reverse DNS" style (eg:
-              '<literal>org.gnome.app</literal>') without the <filename class='extension'>.desktop</filename>
-              suffix.
-            </para>
-            <para>
-              Optionally, if additional parameters are given, they are treated as the names of files to open and
-              may be filenames or URIs.  If no files are given then the application is simply activated.
-            </para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term>
-            <command>list-actions</command>
-            <arg choice="plain"><replaceable>APPID</replaceable></arg>
-          </term>
-          <listitem>
-            <para>
-              List the actions declared in the application's <filename class='extension'>.desktop</filename>
-              file.  The parameter is the application ID, as above.
-            </para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term>
-            <command>action</command>
-            <arg choice="plain"><replaceable>APPID</replaceable></arg>
-            <arg choice="plain"><replaceable>ACTION</replaceable></arg>
-            <arg choice="opt"><replaceable>PARAMETER</replaceable></arg>
-          </term>
-          <listitem>
-            <para>
-              Invokes the named action (in the same way as would occur when activating an action specified in
-              the <filename class='extension'>.desktop</filename> file).
-            </para>
-            <para>
-              The application ID (as above) is the first parameter.  The action name follows.
-            </para>
-            <para>
-              Optionally, following the action name can be one parameter, in GVariant format, given as a single
-              argument.  Make sure to use sufficient quoting.
-            </para>
-          </listitem>
-        </varlistentry>
-
-      </variablelist>
-    </refsect2>
-  </refsect1>
-
-  <refsect1>
-    <title>Examples</title>
-
-    <refsect2>
-      <title>From the commandline</title>
-
-      <para>
-        Launching an application:
-      </para>
-
-      <programlisting>
-        gapplication launch org.example.fooview
-      </programlisting>
-
-      <para>
-        Opening a file with an application:
-      </para>
-
-      <programlisting>
-        gapplication launch org.example.fooview ~/file.foo
-      </programlisting>
-
-      <para>
-        Opening many files with an application:
-      </para>
-
-      <programlisting>
-        gapplication launch org.example.fooview ~/foos/*.foo
-      </programlisting>
-
-      <para>
-        Invoking an action on an application:
-      </para>
-
-      <programlisting>
-        gapplication action org.example.fooview create
-      </programlisting>
-
-      <para>
-        Invoking an action on an application, with an action:
-      </para>
-
-      <programlisting>
-        gapplication action org.example.fooview show-item '"item_id_828739"'
-      </programlisting>
-    </refsect2>
-
-    <refsect2>
-      <title>
-        From the <varname>Exec</varname> lines of a <filename class='extension'>.desktop</filename> file
-      </title>
-
-      <para>
-        The commandline interface of <command>gapplication</command> was designed so that it could be used
-        directly from the <varname>Exec</varname> line of a <filename class='extension'>.desktop</filename>
-        file.
-      </para>
-
-      <para>
-        You might want to do this to allow for backwards compatibility with implementations of the specification
-        that do not understand how to do D-Bus activation, without having to install a separate utility program.
-      </para>
-
-      <para>
-        Consider the following example:
-      </para>
-
-      <programlisting>
-        [Desktop Entry]
-        Version=1.1
-        Type=Application
-        Name=Foo Viewer
-        DBusActivatable=true
-        MimeType=image/x-foo;
-        Exec=gapplication launch org.example.fooview %F
-        Actions=gallery;create;
-
-        [Desktop Action gallery]
-        Name=Browse Gallery
-        Exec=gapplication action org.example.fooview gallery
-
-        [Desktop Action create]
-        Name=Create a new Foo!
-        Exec=gapplication action org.example.fooview create
-      </programlisting>
-    </refsect2>
-
-    <refsect2>
-      <title>From a script</title>
-
-      <para>
-        If installing an application that supports D-Bus activation you may still want to put a file in
-        <filename class='directory'>/usr/bin</filename> so that your program can be started from a terminal.
-      </para>
-
-      <para>
-        It is possible for this file to be a shell script.  The script can handle arguments such as --help and
-        --version directly.  It can also parse other command line arguments and convert them to uses of
-        <command>gapplication</command> to activate the application, open files, or invoke actions.
-      </para>
-
-      <para>
-        Here is a simplified example, as may be installed in <filename>/usr/bin/fooview</filename>:
-      </para>
-
-      <programlisting>
-        #!/bin/sh
-
-        case "$1" in
-          --help)
-            echo "see 'man fooview' for more information"
-            ;;
-
-          --version)
-            echo "fooview 1.2"
-            ;;
-
-          --gallery)
-            gapplication action org.example.fooview gallery
-            ;;
-
-          --create)
-            gapplication action org.example.fooview create
-            ;;
-
-          -*)
-            echo "unrecognised commandline argument"
-            exit 1
-            ;;
-
-          *)
-            gapplication launch org.example.fooview "$@"
-            ;;
-        esac
-      </programlisting>
-    </refsect2>
-  </refsect1>
-
-  <refsect1>
-    <title>See also</title>
-    <para>
-      <ulink url='http://standards.freedesktop.org/desktop-entry-spec/latest/'>Desktop Entry Specification</ulink>,
-      <citerefentry>
-        <refentrytitle>gdbus</refentrytitle>
-        <manvolnum>1</manvolnum>
-      </citerefentry>,
-      <citerefentry>
-        <refentrytitle>xdg-open</refentrytitle>
-        <manvolnum>1</manvolnum>
-      </citerefentry>,
-      <citerefentry>
-        <refentrytitle>desktop-file-validate</refentrytitle>
-        <manvolnum>1</manvolnum>
-      </citerefentry>
-    </para>
-  </refsect1>
-
-</refentry>

docs/reference/gio/gdbus-codegen.rst

@@ -0,0 +1,821 @@
+.. _gdbus-codegen(1):
+.. meta::
+   :copyright: Copyright 2011, 2013, 2016 Red Hat, Inc.
+   :copyright: Copyright 2013, 2022 Emmanuele Bassi
+   :copyright: Copyright 2017 Patrick Griffis
+   :copyright: Copyright 2018 Iñigo Martínez
+   :copyright: Copyright 2018, 2019 Endless Mobile, Inc.
+   :copyright: Copyright 2020 Endless OS Foundation, LLC
+   :copyright: Copyright 2020 Chun-wei Fan
+   :license: LGPL-2.1-or-later
+..
+   This has to be duplicated from above to make it machine-readable by `reuse`:
+   SPDX-FileCopyrightText: 2011, 2013, 2016 Red Hat, Inc.
+   SPDX-FileCopyrightText: 2013, 2022 Emmanuele Bassi
+   SPDX-FileCopyrightText: 2017 Patrick Griffis
+   SPDX-FileCopyrightText: 2018 Iñigo Martínez
+   SPDX-FileCopyrightText: 2018, 2019 Endless Mobile, Inc.
+   SPDX-FileCopyrightText: 2020 Endless OS Foundation, LLC
+   SPDX-FileCopyrightText: 2020 Chun-wei Fan
+   SPDX-License-Identifier: LGPL-2.1-or-later
+
+=============
+gdbus-codegen
+=============
+
+--------------------------------------
+D-Bus code and documentation generator
+--------------------------------------
+
+SYNOPSIS
+--------
+
+|  **gdbus-codegen**
+|    [--help]
+|    [--interface-prefix *org.project.Prefix*]
+|    [--header | --body | --interface-info-header | --interface-info-body | --generate-c-code *OUTFILES*]
+|    [--c-namespace *YourProject*]
+|    [--c-generate-object-manager]
+|    [--c-generate-autocleanup none|objects|all]
+|    [--output-directory *OUTDIR* | --output *OUTFILE*]
+|    [--generate-docbook *OUTFILES*]
+|    [--generate-rst *OUTFILES*]
+|    [--pragma-once]
+|    [--xml-files *FILE*]
+|    [--symbol-decorator *DECORATOR* [--symbol-decorator-header *HEADER*] [--symbol-decorator-define *DEFINE*]]
+|    [--annotate *ELEMENT* *KEY* *VALUE*]…
+|    [--glib-min-required *VERSION*]
+|    [--glib-max-allowed *VERSION*]
+|    *FILE*…
+
+DESCRIPTION
+-----------
+
+``gdbus-codegen`` is used to generate code and/or documentation for one or more
+D-Bus interfaces.
+
+``gdbus-codegen`` reads
+`D-Bus Introspection XML <https://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format>`_
+from files passed as additional arguments on the command line and generates
+output files. It currently supports generating C source code (via ``--body``) or
+header (via ``--header``) and DocBook XML (via ``--generate-docbook``).
+Alternatively, more restricted C source code and headers can be generated, which
+just contain the interface information (as ``GDBusInterfaceInfo`` structures)
+using ``--interface-info-body`` and ``--interface-info-header``.
+
+GENERATING C CODE
+-----------------
+
+When generating C code, a ``GInterface`` derived type is generated for each
+D-Bus interface. Additionally, for every generated type, ``FooBar``, two
+concrete instantiatable types, ``FooBarProxy`` and ``FooBarSkeleton``,
+implementing said interface are also generated. The former is derived from
+``GDBusProxy`` and intended for use on the client side while the latter is
+derived from the ``GDBusInterfaceSkeleton`` type making it easy to export on a
+``GDBusConnection`` either directly or via a ``GDBusObjectManagerServer``
+instance.
+
+For C code generation either ``--body`` that generates source code, ``--header``
+that generates headers, ``--interface-info-body`` that generates interface
+information source code, or ``--interface-info-header`` that generates interface
+information headers, can be used. These options must be used along with
+``--output``, which is used to specify the file to output to.
+
+Both files can be generated at the same time by using ``--generate-c-code``, but
+this option is deprecated. In this case ``--output`` cannot be used due to the
+generation of multiple files. Instead pass ``--output-directory`` to specify the
+directory to put the output files in. By default the current directory will be
+used.
+
+The name of each generated C type is derived from the D-Bus interface name
+stripped with the prefix given with ``--interface-prefix`` and with the dots
+removed and initial characters capitalized. For example, for the D-Bus
+interface ``com.acme.Coyote`` the name used is ``ComAcmeCoyote``. For the D-Bus
+interface ``org.project.Bar.Frobnicator`` with ``--interface-prefix`` set to
+``org.project.``, the name used is ``BarFrobnicator``.
+
+For methods, signals and properties, if not specified, the name defaults to the
+name of the method, signal or property.
+
+Two forms of the name are used — the CamelCase form and the lower-case form. The
+CamelCase form is used for the ``GType`` and struct name, while lower-case form
+is used in function names. The lower-case form is calculated by converting from
+CamelCase to lower-case and inserting underscores at word boundaries (using
+certain heuristics).
+
+If the value given by the ``org.gtk.GDBus.C.Name`` annotation or the
+``--c-namespace`` option contains an underscore (sometimes called *Ugly_Case*),
+then the camel-case name is derived by removing all underscores, and the
+lower-case name is derived by lower-casing the string. This is useful in some
+situations where abbreviations are used. For example, if the annotation is used
+on the interface ``net.MyCorp.MyApp.iSCSITarget`` with the value
+``iSCSI_Target`` the CamelCase form is ``iSCSITarget`` while the lower-case form
+is ``iscsi_target``. If the annotation is used on the method ``EjectTheiPod``
+with the value ``Eject_The_iPod``, the lower-case form is ``eject_the_ipod``.
+
+GENERATING DOCBOOK DOCUMENTATION
+--------------------------------
+
+Each generated DocBook XML file (see the ``--generate-docbook`` option for
+details) is a ``RefEntry`` article describing the D-Bus interface. (See the
+`DocBook documentation <https://tdg.docbook.org/tdg/4.5/refentry.html>`_.)
+
+GENERATING RESTRUCTUREDTEXT DOCUMENTATION
+-----------------------------------------
+
+Each generated reStructuredText file (see the ``--generate-rst`` option for
+details) is a plain text
+`reStructuredText <https://docutils.sourceforge.io/rst.html>`_ document
+describing the D-Bus interface.
+
+OPTIONS
+-------
+
+The following options are supported:
+
+``-h``, ``--help``
+
+  Show help and exit.
+
+``--xml-files`` *FILE*
+
+  This option is deprecated; use positional arguments instead.  The D-Bus
+  introspection XML file.
+
+``--interface-prefix`` *org.project.Prefix.*
+
+  A prefix to strip from all D-Bus interface names when
+  calculating the type name for the C binding and the DocBook ``sortas``
+  `attribute <https://tdg.docbook.org/tdg/4.5/primary.html>`_.
+
+``--generate-docbook`` *OUTFILES*
+
+  Generate DocBook Documentation for each D-Bus interface and put it in
+  ``OUTFILES-NAME.xml`` where ``NAME`` is a placeholder for the interface
+  name, e.g. ``net.Corp.FooBar`` and so on.
+
+  Pass ``--output-directory`` to specify the directory to put the output files
+  in. By default the current directory will be used.
+
+``--generate-rst`` *OUTFILES*
+
+  Generate reStructuredText Documentation for each D-Bus interface and put it in
+  ``OUTFILES-NAME.rst`` where ``NAME`` is a placeholder for the interface
+  name, e.g. ``net.Corp.FooBar`` and so on.
+
+  Pass ``--output-directory`` to specify the directory to put the output files
+  in. By default the current directory will be used.
+
+``--generate-c-code`` *OUTFILES*
+
+  Generate C code for all D-Bus interfaces and put it in ``OUTFILES.c`` and
+  ``OUTFILES.h`` including any sub-directories. If you want the files to be
+  output in a different location use ``--output-directory`` as ``OUTFILES.h``
+  including sub-directories will be referenced from ``OUTFILES.c``.
+
+  The full paths would then be
+  ``$(OUTDIR)/$(dirname $OUTFILES)/$(basename $OUTFILES).{c,h}``.
+
+``--c-namespace`` *YourProject*
+
+  The namespace to use for generated C code. This is expected to be in
+  `CamelCase <https://en.wikipedia.org/wiki/Camel_case>`_ or *Ugly_Case* (see
+  above).
+
+``--pragma-once``
+
+  If this option is passed, the
+  `#pragma once <https://en.wikipedia.org/wiki/Pragma_once>`_ preprocessor
+  directive is used instead of include guards.
+
+``--c-generate-object-manager``
+
+  If this option is passed, suitable ``GDBusObject``, ``GDBusObjectProxy``,
+  ``GDBusObjectSkeleton`` and ``GDBusObjectManagerClient`` subclasses are
+  generated.
+
+``--c-generate-autocleanup`` none|objects|all
+
+  This option influences what types autocleanup functions are
+  generated for. ``none`` means to not generate any autocleanup functions.
+  ``objects`` means to generate them for object types, and ``all`` means to
+  generate them for object types and interfaces. The default is ``objects``
+  due to a corner case in backwards compatibility with a few projects,
+  but you should likely switch your project to use ``all``.
+  This option was added in GLib 2.50.
+
+``--output-directory`` *OUTDIR*
+
+  Directory to output generated source to. Equivalent to changing directory
+  before generation.
+
+  This option cannot be used with ``--body``, ``--header``,
+  ``--interface-info-body`` or ``--interface-info-header``; and ``--output``
+  must be used.
+
+``--header``
+
+  If this option is passed, it will generate the header code and write it to the
+  disk by using the path and file name provided by ``--output``.
+
+  Using ``--generate-c-code``, ``--generate-docbook`` or ``--output-directory``
+  are not allowed to be used along with ``--header`` and ``--body`` options,
+  because these options are used to generate only one file.
+
+``--body``
+
+  If this option is passed, it will generate the source code and write it to the
+  disk by using the path and file name provided by ``--output``.
+
+  Using ``--generate-c-code``, ``--generate-docbook`` or ``--output-directory``
+  are not allowed to be used along with ``--header`` and ``--body`` options,
+  because these options are used to generate only one file.
+
+``--interface-info-header``
+
+  If this option is passed, it will generate the header code for the
+  ``GDBusInterfaceInfo`` structures only and will write it to the disk by using
+  the path and file name provided by ``--output``.
+
+  Using ``--generate-c-code``, ``--generate-docbook`` or ``--output-directory``
+  are not allowed to be used along with the ``--interface-info-header`` and
+  ``--interface-info-body`` options, because these options are used to generate
+  only one file.
+
+``--interface-info-body``
+
+  If this option is passed, it will generate the source code for the
+  ``GDBusInterfaceInfo`` structures only and will write it to the disk by using
+  the path and file name provided by ``--output``.
+
+  Using ``--generate-c-code``, ``--generate-docbook`` or ``--output-directory``
+  are not allowed to be used along with the ``--interface-info-header`` and
+  ``--interface-info-body`` options, because these options are used to generate
+  only one file.
+
+``--symbol-decorator`` *DECORATOR*
+
+  If a ``DECORATOR`` is passed in with this option, all the generated function
+  prototypes in the generated header will be marked with ``DECORATOR``. This can
+  be used, for instance, to export symbols from code generated with
+  ``gdbus-codegen``.
+
+  This option was added in GLib 2.66.
+
+``--symbol-decorator-header`` *HEADER*
+
+  If a ``HEADER`` is passed in with this option, the generated header will put a
+  ``#include HEADER`` before the rest of the items, except for the inclusion
+  guards or ``#pragma once`` (if ``--pragma-once`` is used).  This is used if
+  using another header file is needed for the decorator passed in via
+  ``--symbol-decorator`` to be defined.
+
+  This option was added in GLib 2.66.
+
+  This option can only be used if ``--symbol-decorator`` is used.
+
+``--symbol-decorator-define`` *DEFINE*
+
+  If a ``DEFINE`` is passed in with this option, the generated source will add a
+  ``#define DEFINE`` before the rest of the items.  This is used if a particular
+  macro is needed to ensure the decorator passed in via ``--symbol-decorator``
+  uses the correct definition when the generated source is being compiled.
+
+  This option was added in GLib 2.66.
+
+  This option can only be used if ``--symbol-decorator`` is used.
+
+``--output`` *OUTFILE*
+
+  The full path where the header (``--header``, ``--interface-info-header``) or
+  the source code (``--body``, ``--interface-info-body``) will be written, using
+  the path and filename provided by ``--output``. The full path could be
+  something like ``$($OUTFILE).{c,h}``.
+
+  Using ``--generate-c-code``, ``--generate-docbook`` or ``--output-directory``
+  is not allowed along with ``--output``, because the latter is used to generate
+  only one file.
+
+  Since GLib 2.80, if *OUTFILE* is the literal string ``-``, the header
+  or source code will be written to standard output.
+
+  For ``--body`` and ``--interface-info-body``, the generated code will not
+  automatically ``#include`` a corresponding header file when writing to
+  standard output, because there is no obvious name for that header file.
+  This might make it necessary to use ``cc -include foo.h``, or generate a
+  filename like ``foo-impl.h`` and ``#include`` it into a wrapper ``.c`` file.
+
+  For ``--header`` and ``--interface-info-header``, there is no obvious
+  name for a traditional multiple-inclusion guard when writing to standard
+  output, so using the ``--pragma-once`` option is recommended.
+
+  In the rare situation that the intended output filename starts with ``-``,
+  it should be prefixed with ``./``.
+
+``--annotate`` *ELEMENT* *KEY* *VALUE*
+
+  Used to inject D-Bus annotations into the given XML files. It can be used with
+  interfaces, methods, signals, properties and arguments in the following way::
+
+     gdbus-codegen --c-namespace MyApp                           \
+       --generate-c-code myapp-generated                         \
+       --annotate "org.project.InterfaceName"                    \
+         org.gtk.GDBus.C.Name MyFrobnicator                      \
+       --annotate "org.project.InterfaceName:Property"           \
+         bar bat                                                 \
+       --annotate "org.project.InterfaceName.Method()"           \
+         org.freedesktop.DBus.Deprecated true                    \
+       --annotate "org.project.InterfaceName.Method()[arg_name]" \
+         snake hiss                                              \
+       --annotate "org.project.InterfaceName::Signal"            \
+         cat meow                                                \
+       --annotate "org.project.InterfaceName::Signal[arg_name]"  \
+         dog wuff                                                \
+       myapp-dbus-interfaces.xml
+
+  Any UTF-8 string can be used for *KEY* and *VALUE*.
+
+``--glib-min-required`` *VERSION*
+
+  Specifies the minimum version of GLib which the code generated by
+  ``gdbus-codegen`` can depend on. This may be used to make
+  backwards-incompatible changes in the output or behaviour of ``gdbus-codegen``
+  in future, which users may opt in to by increasing the value they pass for
+  ``--glib-min-required``. If this option is not passed, the output from
+  ``gdbus-codegen`` is guaranteed to be compatible with all versions of GLib
+  from 2.30 upwards, as that is when ``gdbus-codegen`` was first released.
+
+  Note that some version parameters introduce incompatible changes: all callers
+  of the generated code might need to be updated, and if the generated code is
+  part of a library’s API or ABI, then increasing the version parameter can
+  result in an API or ABI break.
+
+  The version number must be of the form ``MAJOR.MINOR.MICRO``, where all parts
+  are integers. ``MINOR`` and ``MICRO`` are optional. The version number may not
+  be smaller than ``2.30``.
+
+  If the version number is ``2.64`` or greater, the generated code will
+  have the following features:
+
+  1. If a method has ``h`` (file descriptor) parameter(s), a ``GUnixFDList``
+     parameter will exist in the generated code for it (whereas previously the
+     annotation ``org.gtk.GDBus.C.UnixFD`` was required), and
+  2. Method call functions will have two additional arguments to allow the user
+     to specify ``GDBusCallFlags`` and a timeout value, as is possible when
+     using ``g_dbus_proxy_call()``.
+
+``--glib-max-allowed`` *VERSION*
+
+  Specifies the maximum version of GLib which the code generated by
+  ``gdbus-codegen`` can depend on. This may be used to ensure that code
+  generated by ``gdbus-codegen`` is compilable with specific older versions of
+  GLib that your software has to support.
+
+  The version number must be of the form ``MAJOR.MINOR.MICRO``, where all parts
+  are integers. ``MINOR`` and ``MICRO`` are optional. The version number must be
+  greater than or equal to that passed to ``--glib-min-required``.
+  It defaults to the version of GLib which provides this ``gdbus-codegen``.
+
+SUPPORTED D-BUS ANNOTATIONS
+---------------------------
+
+The following D-Bus annotations are supported by ``gdbus-codegen``:
+
+``org.freedesktop.DBus.Deprecated``
+
+  Can be used on any ``<interface>``, ``<method>``, ``<signal>`` and
+  ``<property>`` element to specify that the element is deprecated if its value
+  is ``true``. Note that this annotation is defined in the
+  `D-Bus specification <https://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format>`_
+  and can only assume the values ``true`` and ``false``. In particular, you
+  cannot specify the version that the element was deprecated in nor any helpful
+  deprecation message. Such information should be added to the element
+  documentation instead.
+
+  When generating C code, this annotation is used to add ``G_GNUC_DEPRECATED``
+  to generated functions for the element.
+
+  When generating DocBook XML, a deprecation warning will appear along the
+  documentation for the element.
+
+``org.gtk.GDBus.Since``
+
+  Can be used on any ``<interface>``, ``<method>``, ``<signal>`` and
+  ``<property>`` element to specify the version (any free-form string but
+  compared using a version-aware sort function) the element appeared in.
+
+  When generating C code, this field is used to ensure
+  function pointer order for preserving ABI/API, see ‘STABILITY GUARANTEES’.
+
+  When generating DocBook XML, the value of this tag appears in the
+  documentation.
+
+``org.gtk.GDBus.DocString``
+
+  A string with DocBook content for documentation. This annotation can
+  be used on ``<interface>``, ``<method>``, ``<signal>``, ``<property>`` and
+  ``<arg>`` elements.
+
+``org.gtk.GDBus.DocString.Short``
+
+  A string with DocBook content for short/brief documentation. This annotation
+  can only be used on ``<interface>`` elements.
+
+``org.gtk.GDBus.C.Name``
+
+  Can be used on any ``<interface>``, ``<method>``, ``<signal>`` and
+  ``<property>`` element to specify the name to use when generating C code. The
+  value is expected to be in
+  `CamelCase <https://en.wikipedia.org/wiki/Camel_case>`_ or *Ugly_Case* (see
+  above).
+
+``org.gtk.GDBus.C.ForceGVariant``
+
+  If set to a non-empty string, a ``GVariant`` instance will be used instead of
+  the natural C type. This annotation can be used on any ``<arg>`` and
+  ``<property>`` element.
+
+``org.gtk.GDBus.C.UnixFD``
+
+  If set to a non-empty string, the generated code will include parameters to
+  exchange file descriptors using the ``GUnixFDList`` type. This annotation can
+  be used on ``<method>`` elements.
+
+As an easier alternative to using the ``org.gtk.GDBus.DocString`` annotation,
+note that parser used by ``gdbus-codegen`` parses XML comments in a way similar
+to `gtk-doc <https://developer-old.gnome.org/gtk-doc-manual/stable/>`_::
+
+   <!--
+     net.Corp.Bar:
+     @short_description: A short description
+
+     A <emphasis>longer</emphasis> description.
+
+     This is a new paragraph.
+   -->
+   <interface name="net.corp.Bar">
+     <!--
+       FooMethod:
+       @greeting: The docs for greeting parameter.
+       @response: The docs for response parameter.
+
+       The docs for the actual method.
+     -->
+     <method name="FooMethod">
+       <arg name="greeting" direction="in" type="s"/>
+       <arg name="response" direction="out" type="s"/>
+     </method>
+
+     <!--
+       BarSignal:
+       @blah: The docs for blah parameter.
+       @boo: The docs for boo parameter.
+       @since: 2.30
+
+       The docs for the actual signal.
+     -->
+     <signal name="BarSignal">
+       <arg name="blah" type="s"/>
+       <arg name="boo" type="s"/>
+     </signal>
+
+     <!-- BazProperty: The docs for the property. -->
+     <property name="BazProperty" type="s" access="read"/>
+   </interface>
+
+Note that ``@since`` can be used in any inline documentation bit (e.g. for
+interfaces, methods, signals and properties) to set the ``org.gtk.GDBus.Since``
+annotation. For the ``org.gtk.GDBus.DocString`` annotation (and inline
+comments), note that substrings of the form ``#net.Corp.Bar``,
+``net.Corp.Bar.FooMethod()``, ``#net.Corp.Bar::BarSignal`` and
+``#net.Corp.InlineDocs:BazProperty`` are all expanded to links to the respective
+interface, method, signal and property. Additionally, substrings starting with
+``@`` and ``%`` characters are rendered as
+`parameter <https://tdg.docbook.org/tdg/4.5/parameter.html>`_ and
+`constant <https://tdg.docbook.org/tdg/4.5/constant.html>`_ respectively.
+
+If both XML comments and ``org.gtk.GDBus.DocString`` or
+``org.gtk.GDBus.DocString.Short`` annotations are present, the latter wins.
+
+EXAMPLE
+-------
+
+Consider the following D-Bus Introspection XML::
+
+   <node>
+     <interface name="net.Corp.MyApp.Frobber">
+       <method name="HelloWorld">
+         <arg name="greeting" direction="in" type="s"/>
+         <arg name="response" direction="out" type="s"/>
+       </method>
+
+       <signal name="Notification">
+         <arg name="icon_blob" type="ay"/>
+         <arg name="height" type="i"/>
+         <arg name="messages" type="as"/>
+       </signal>
+
+       <property name="Verbose" type="b" access="readwrite"/>
+     </interface>
+   </node>
+
+If ``gdbus-codegen`` is used on this file like this::
+
+   gdbus-codegen --generate-c-code myapp-generated       \
+                 --c-namespace MyApp                     \
+                 --interface-prefix net.corp.MyApp.      \
+                 net.Corp.MyApp.Frobber.xml
+
+two files called ``myapp-generated.[ch]`` are generated. The files provide an
+abstract ``GTypeInterface`` derived type called ``MyAppFrobber`` as well as two
+instantiatable types with the same name but suffixed with ``Proxy`` and
+``Skeleton``. The generated file, roughly, contains the following facilities::
+
+   /* GType macros for the three generated types */
+   #define MY_APP_TYPE_FROBBER (my_app_frobber_get_type ())
+   #define MY_APP_TYPE_FROBBER_SKELETON (my_app_frobber_skeleton_get_type ())
+   #define MY_APP_TYPE_FROBBER_PROXY (my_app_frobber_proxy_get_type ())
+
+   typedef struct _MyAppFrobber MyAppFrobber; /* Dummy typedef */
+
+   typedef struct
+   {
+     GTypeInterface parent_iface;
+
+     /* Signal handler for the ::notification signal */
+     void (*notification) (MyAppFrobber *proxy,
+                           GVariant *icon_blob,
+                           gint height,
+                           const gchar* const *messages);
+
+     /* Signal handler for the ::handle-hello-world signal */
+     gboolean (*handle_hello_world) (MyAppFrobber *proxy,
+                                     GDBusMethodInvocation *invocation,
+                                     const gchar *greeting);
+   } MyAppFrobberIface;
+
+   /* Asynchronously calls HelloWorld() */
+   void
+   my_app_frobber_call_hello_world (MyAppFrobber *proxy,
+                                    const gchar *greeting,
+                                    GCancellable *cancellable,
+                                    GAsyncReadyCallback callback,
+                                    gp ointer user_data);
+   gboolean
+   my_app_frobber_call_hello_world_finish (MyAppFrobber *proxy,
+                                           gchar **out_response,
+                                           GAsyncResult *res,
+                                           GError **error);
+
+   /* Synchronously calls HelloWorld(). Blocks calling thread. */
+   gboolean
+   my_app_frobber_call_hello_world_sync (MyAppFrobber *proxy,
+                                         const gchar *greeting,
+                                         gchar **out_response,
+                                         GCancellable *cancellable,
+                                         GError **error);
+
+   /* Completes handling the HelloWorld() method call */
+   void
+   my_app_frobber_complete_hello_world (MyAppFrobber *object,
+                                        GDBusMethodInvocation *invocation,
+                                        const gchar *response);
+
+   /* Emits the ::notification signal / Notification() D-Bus signal */
+   void
+   my_app_frobber_emit_notification (MyAppFrobber *object,
+                                     GVariant *icon_blob,
+                                     gint height,
+                                     const gchar* const *messages);
+
+   /* Gets the :verbose GObject property / Verbose D-Bus property.
+    * Does no blocking I/O.
+    */
+   gboolean my_app_frobber_get_verbose (MyAppFrobber *object);
+
+   /* Sets the :verbose GObject property / Verbose D-Bus property.
+    * Does no blocking I/O.
+    */
+   void my_app_frobber_set_verbose (MyAppFrobber *object,
+                                    gboolean      value);
+
+   /* Gets the interface info */
+   GDBusInterfaceInfo *my_app_frobber_interface_info (void);
+
+   /* Creates a new skeleton object, ready to be exported */
+   MyAppFrobber *my_app_frobber_skeleton_new (void);
+
+   /* Client-side proxy constructors.
+    *
+    * Additionally, _new_for_bus(), _new_for_bus_finish() and
+    * _new_for_bus_sync() proxy constructors are also generated.
+    */
+   void
+   my_app_frobber_proxy_new        (GDBusConnection     *connection,
+                                    GDBusProxyFlags      flags,
+                                    const gchar         *name,
+                                    const gchar         *object_path,
+                                    GCancellable        *cancellable,
+                                    GAsyncReadyCallback  callback,
+                                    gpointer             user_data);
+   MyAppFrobber *
+   my_app_frobber_proxy_new_finish (GAsyncResult        *res,
+                                    GError             **error);
+   MyAppFrobber *
+   my_app_frobber_proxy_new_sync   (GDBusConnection     *connection,
+                                    GDBusProxyFlags      flags,
+                                    const gchar         *name,
+                                    const gchar         *object_path,
+                                    GCancellable        *cancellable,
+                                    GError             **error);
+
+Thus, for every D-Bus method, there will be three C functions for calling the
+method, one ``GObject`` signal for handling an incoming call and one C function
+for completing an incoming call. For every D-Bus signal, there’s one ``GObject``
+signal and one C function for emitting it. For every D-Bus property, two C
+functions are generated (one setter, one getter) and one ``GObject`` property.
+The following table summarizes the generated facilities and where they are
+applicable:
+
+.. table::
+   :widths: auto
+
+   ====================  =========================================================  =================================================================================================================
+   Symbol type           Client                                                     Server
+   ====================  =========================================================  =================================================================================================================
+   Types                 Use ``MyAppFrobberProxy``.                                 Any type implementing the ``MyAppFrobber`` interface.
+   Methods               Use ``m_a_f_hello_world()`` to call.                       Receive via the ``handle_hello_world()`` signal handler. Complete the call with ``m_a_f_complete_hello_world()``.
+   Signals               Connect to the ``::notification`` signal.                  Use ``m_a_f_emit_notification()`` to emit signal.
+   Properties (Reading)  Use ``m_a_f_get_verbose()`` or the ``:verbose`` property.  Implement the ``get_property()`` vfunc of ``GObject``.
+   Properties (writing)  Use ``m_a_f_set_verbose()`` or the ``:verbose`` property.  Implement the ``set_property()`` vfunc of ``GObject``.
+   ====================  =========================================================  =================================================================================================================
+
+Client-side usage
+^^^^^^^^^^^^^^^^^
+
+You can use the generated proxy type with the generated constructors::
+
+   MyAppFrobber *proxy;
+   GError *error;
+
+   error = NULL;
+   proxy = my_app_frobber_proxy_new_for_bus_sync (
+               G_BUS_TYPE_SESSION,
+               G_DBUS_PROXY_FLAGS_NONE,
+               "net.Corp.MyApp",              /* bus name */
+               "/net/Corp/MyApp/SomeFrobber", /* object */
+               NULL,                          /* GCancellable* */
+               &error);
+   /* do stuff with proxy */
+   g_object_unref (proxy);
+
+Instead of using the generic ``GDBusProxy`` facilities, one can use the
+generated methods such as ``my_app_frobber_call_hello_world()`` to invoke
+the ``net.Corp.MyApp.Frobber.HelloWorld()`` D-Bus method, connect to the
+``::notification`` ``GObject`` signal to receive the
+``net.Corp.MyApp.Frobber::Notification`` D-Bus signal and get/set the
+``net.Corp.MyApp.Frobber:Verbose`` D-Bus Property using either the ``GObject``
+property ``:verbose`` or the ``my_app_get_verbose()`` and
+``my_app_set_verbose()`` methods. Use the standard ``GObject::notify`` signal to
+listen to property changes.
+
+Note that all property access is via the ``GDBusProxy`` property cache so no I/O
+is ever done when reading properties. Also note that setting a property will
+cause the ``org.freedesktop.DBus.Properties.Set`` method
+(`documentation <https://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties>`_)
+to be called on the remote object. This call, however, is asynchronous so
+setting a property won’t block. Further, the change is delayed and no error
+checking is possible.
+
+Server-side usage
+^^^^^^^^^^^^^^^^^
+
+The generated ``MyAppFrobber`` interface is designed so it is easy to implement
+it in a ``GObject`` subclass. For example, to handle ``HelloWorld()`` method
+invocations, set the vfunc for ``handle_hello_hello_world()`` in the
+``MyAppFrobberIface`` structure. Similarly, to handle the
+``net.Corp.MyApp.Frobber:Verbose`` property override the ``:verbose``
+``GObject`` property from the subclass. To emit a signal, use e.g.
+``my_app_emit_signal()`` or ``g_signal_emit_by_name()``.
+
+Instead of subclassing, it is often easier to use the generated
+``MyAppFrobberSkeleton`` subclass. To handle incoming method calls, use
+``g_signal_connect()`` with the ``::handle-*`` signals and instead of
+overriding the ``get_property()`` and ``set_property()`` vfuncs from
+``GObject``, use ``g_object_get()`` and ``g_object_set()`` or the generated
+property getters and setters (the generated class has an internal property bag
+implementation).
+
+For example::
+
+   static gboolean
+   on_handle_hello_world (MyAppFrobber           *interface,
+                          GDBusMethodInvocation  *invocation,
+                          const gchar            *greeting,
+                          gpointer                user_data)
+   {
+     if (g_strcmp0 (greeting, "Boo") != 0)
+       {
+         gchar *response;
+         response = g_strdup_printf ("Word! You said ‘%s’.", greeting);
+         my_app_complete_hello_world (interface, invocation, response);
+         g_free (response);
+       }
+     else
+       {
+         g_dbus_method_invocation_return_error (invocation,
+                    MY_APP_ERROR,
+                    MY_APP_ERROR_NO_WHINING,
+                    "Hey, %s, there will be no whining!",
+                    g_dbus_method_invocation_get_sender (invocation));
+       }
+     return TRUE;
+   }
+
+     […]
+
+     interface = my_app_frobber_skeleton_new ();
+     my_app_frobber_set_verbose (interface, TRUE);
+
+     g_signal_connect (interface,
+                       "handle-hello-world",
+                       G_CALLBACK (on_handle_hello_world),
+                       some_user_data);
+
+     […]
+
+     error = NULL;
+     if (!g_dbus_interface_skeleton_export (G_DBUS_INTERFACE_SKELETON (interface),
+                                            connection,
+                                            "/path/of/dbus_object",
+                                            &error))
+       {
+         /* handle error */
+       }
+
+To facilitate atomic changesets (multiple properties changing at the same time),
+``GObject::notify`` signals are queued up when received. The queue is drained in
+an idle handler (which is called from the thread-default main loop of the thread
+where the skeleton object was constructed) and will cause emissions of the
+``org.freedesktop.DBus.Properties::PropertiesChanged``
+(`documentation <https://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties>`_)
+signal with all the properties that have changed. Use
+``g_dbus_interface_skeleton_flush()`` or ``g_dbus_object_skeleton_flush()`` to
+empty the queue immediately. Use ``g_object_freeze_notify()`` and
+``g_object_thaw_notify()`` for atomic changesets if on a different thread.
+
+C TYPE MAPPING
+--------------
+
+Scalar types (type strings ``b``, ``y``, ``n``, ``q``, ``i``, ``u``, ``x``,
+``t`` and ``d``), strings (type strings ``s``, ``ay``, ``o`` and ``g``) and
+arrays of strings (type strings ``as``, ``ao`` and ``aay``) are mapped to the
+natural types, e.g. ``gboolean``, ``gdouble``, ``gint``, ``gchar*``, ``gchar**``
+and so on. Everything else is mapped to the ``GVariant`` type.
+
+This automatic mapping can be turned off by using the annotation
+``org.gtk.GDBus.C.ForceGVariant`` — if used then a ``GVariant`` is always
+exchanged instead of the corresponding native C type. This annotation may be
+convenient to use when using bytestrings (type string ``ay``) for data that
+could have embedded nul bytes.
+
+STABILITY GUARANTEES
+--------------------
+
+The generated C functions are guaranteed to not change their ABI. That is, if a
+method, signal or property does not change its signature in the introspection
+XML, the generated C functions will not change their C ABI either. The ABI of
+the generated instance and class structures will be preserved as well.
+
+The ABI of the generated ``GType`` instances will be preserved only if the
+``org.gtk.GDBus.Since`` annotation is used judiciously — this is because the
+VTable for the ``GInterface`` relies on function pointers for signal handlers.
+Specifically, if a D-Bus method, property or signal or is added to a D-Bus
+interface, then ABI of the generated ``GInterface`` type is preserved if, and
+only if, each added method, property signal is annotated with the
+``org.gtk.GDBus.Since`` annotation using a greater version number than previous
+versions.
+
+The generated C code currently happens to be annotated with
+`gtk-doc <https://developer-old.gnome.org/gtk-doc-manual/stable/>`_ and
+`GObject Introspection <https://gi.readthedocs.io/en/latest/>`_ comments and
+annotations. The layout and contents might change in the future so no guarantees
+about e.g. ``SECTION`` usage etc. are given.
+
+While the generated DocBook for D-Bus interfaces isn’t expected to change, no
+guarantees are given at this point.
+
+It is important to note that the generated code should not be checked into
+version control systems, nor it should be included in distributed source
+archives.
+
+BUGS
+----
+
+Please send bug reports to either the distribution bug tracker or the
+`upstream bug tracker <https://gitlab.gnome.org/GNOME/glib/issues/new>`_.
+
+SEE ALSO
+--------
+
+`gdbus(1) <man:gdbus(1)>`_

docs/reference/gio/gdbus-object-manager-example/.gitignore

@@ -1 +0,0 @@
-gdbus-object-manager-example-overrides.txt

docs/reference/gio/gdbus-object-manager-example/gdbus-object-manager-example-docs.xml

@@ -1,19 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
-]>
-<book lang="en" xmlns:xi="http://www.w3.org/2003/XInclude">
-  <part>
-    <title>GDBus ObjctManager Example</title>
-    <chapter>
-      <title>Interfaces</title>
-      <xi:include href="xml/ExampleAnimal.xml"/>
-      <xi:include href="xml/ExampleCat.xml"/>
-      <xi:include href="xml/ExampleObject.xml"/>
-      <xi:include href="xml/ExampleObjectManagerClient.xml"/>
-    </chapter>
-  </part>
-
-  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
-</book>

docs/reference/gio/gdbus-object-manager-example/gdbus-object-manager-example-sections.txt

@@ -1,161 +0,0 @@
-<SECTION>
-<FILE>ExampleAnimal</FILE>
-<TITLE>ExampleAnimal</TITLE>
-ExampleAnimal
-ExampleAnimalIface
-example_animal_interface_info
-example_animal_override_properties
-example_animal_call_poke
-example_animal_call_poke_finish
-example_animal_call_poke_sync
-example_animal_complete_poke
-example_animal_emit_jumped
-example_animal_get_mood
-example_animal_get_foo
-example_animal_get_bar
-example_animal_dup_mood
-example_animal_dup_foo
-example_animal_dup_bar
-example_animal_set_mood
-example_animal_set_foo
-example_animal_set_bar
-ExampleAnimalProxy
-ExampleAnimalProxyClass
-example_animal_proxy_new
-example_animal_proxy_new_finish
-example_animal_proxy_new_sync
-example_animal_proxy_new_for_bus
-example_animal_proxy_new_for_bus_finish
-example_animal_proxy_new_for_bus_sync
-ExampleAnimalSkeleton
-ExampleAnimalSkeletonClass
-example_animal_skeleton_new
-<SUBSECTION Standard>
-example_animal_get_type
-example_animal_proxy_get_type
-example_animal_skeleton_get_type
-ExampleAnimalSkeletonPrivate
-ExampleAnimalProxyPrivate
-EXAMPLE_TYPE_ANIMAL
-EXAMPLE_TYPE_ANIMAL_PROXY
-EXAMPLE_TYPE_ANIMAL_SKELETON
-EXAMPLE_ANIMAL
-EXAMPLE_ANIMAL_GET_IFACE
-EXAMPLE_ANIMAL_PROXY
-EXAMPLE_ANIMAL_PROXY_CLASS
-EXAMPLE_ANIMAL_PROXY_GET_CLASS
-EXAMPLE_ANIMAL_SKELETON
-EXAMPLE_ANIMAL_SKELETON_CLASS
-EXAMPLE_ANIMAL_SKELETON_GET_CLASS
-EXAMPLE_IS_ANIMAL
-EXAMPLE_IS_ANIMAL_PROXY
-EXAMPLE_IS_ANIMAL_PROXY_CLASS
-EXAMPLE_IS_ANIMAL_SKELETON
-EXAMPLE_IS_ANIMAL_SKELETON_CLASS
-</SECTION>
-
-<SECTION>
-<FILE>ExampleCat</FILE>
-<TITLE>ExampleCat</TITLE>
-ExampleCat
-ExampleCatIface
-example_cat_interface_info
-example_cat_override_properties
-ExampleCatProxy
-ExampleCatProxyClass
-example_cat_proxy_new
-example_cat_proxy_new_finish
-example_cat_proxy_new_sync
-example_cat_proxy_new_for_bus
-example_cat_proxy_new_for_bus_finish
-example_cat_proxy_new_for_bus_sync
-ExampleCatSkeleton
-ExampleCatSkeletonClass
-example_cat_skeleton_new
-<SUBSECTION Standard>
-example_cat_get_type
-example_cat_proxy_get_type
-example_cat_skeleton_get_type
-ExampleCatProxyPrivate
-ExampleCatSkeletonPrivate
-EXAMPLE_TYPE_CAT
-EXAMPLE_TYPE_CAT_PROXY
-EXAMPLE_TYPE_CAT_SKELETON
-EXAMPLE_CAT
-EXAMPLE_CAT_GET_IFACE
-EXAMPLE_CAT_PROXY
-EXAMPLE_CAT_PROXY_CLASS
-EXAMPLE_CAT_PROXY_GET_CLASS
-EXAMPLE_CAT_SKELETON
-EXAMPLE_CAT_SKELETON_CLASS
-EXAMPLE_CAT_SKELETON_GET_CLASS
-EXAMPLE_IS_CAT
-EXAMPLE_IS_CAT_PROXY
-EXAMPLE_IS_CAT_PROXY_CLASS
-EXAMPLE_IS_CAT_SKELETON
-EXAMPLE_IS_CAT_SKELETON_CLASS
-</SECTION>
-
-<SECTION>
-<FILE>ExampleObject</FILE>
-<TITLE>ExampleObject</TITLE>
-ExampleObject
-ExampleObjectIface
-example_object_get_animal
-example_object_get_cat
-example_object_peek_animal
-example_object_peek_cat
-ExampleObjectProxy
-ExampleObjectProxyClass
-example_object_proxy_new
-ExampleObjectSkeleton
-ExampleObjectSkeletonClass
-example_object_skeleton_new
-example_object_skeleton_set_animal
-example_object_skeleton_set_cat
-<SUBSECTION Standard>
-example_object_get_type
-example_object_proxy_get_type
-example_object_skeleton_get_type
-ExampleObjectProxyPrivate
-ExampleObjectSkeletonPrivate
-EXAMPLE_IS_OBJECT
-EXAMPLE_IS_OBJECT_PROXY
-EXAMPLE_IS_OBJECT_PROXY_CLASS
-EXAMPLE_IS_OBJECT_SKELETON
-EXAMPLE_IS_OBJECT_SKELETON_CLASS
-EXAMPLE_OBJECT
-EXAMPLE_OBJECT_GET_IFACE
-EXAMPLE_OBJECT_PROXY
-EXAMPLE_OBJECT_PROXY_CLASS
-EXAMPLE_OBJECT_PROXY_GET_CLASS
-EXAMPLE_OBJECT_SKELETON
-EXAMPLE_OBJECT_SKELETON_CLASS
-EXAMPLE_OBJECT_SKELETON_GET_CLASS
-EXAMPLE_TYPE_OBJECT
-EXAMPLE_TYPE_OBJECT_PROXY
-EXAMPLE_TYPE_OBJECT_SKELETON
-</SECTION>
-
-<SECTION>
-<FILE>ExampleObjectManagerClient</FILE>
-<TITLE>ExampleObjectManagerClient</TITLE>
-ExampleObjectManagerClient
-ExampleObjectManagerClientClass
-example_object_manager_client_get_proxy_type
-example_object_manager_client_new
-example_object_manager_client_new_finish
-example_object_manager_client_new_sync
-example_object_manager_client_new_for_bus
-example_object_manager_client_new_for_bus_finish
-example_object_manager_client_new_for_bus_sync
-<SUBSECTION Standard>
-example_object_manager_client_get_type
-EXAMPLE_IS_OBJECT_MANAGER_CLIENT
-EXAMPLE_IS_OBJECT_MANAGER_CLIENT_CLASS
-EXAMPLE_OBJECT_MANAGER_CLIENT
-EXAMPLE_OBJECT_MANAGER_CLIENT_CLASS
-EXAMPLE_OBJECT_MANAGER_CLIENT_GET_CLASS
-EXAMPLE_TYPE_OBJECT_MANAGER_CLIENT
-ExampleObjectManagerClientPrivate
-</SECTION>

docs/reference/gio/gdbus-object-manager-example/meson.build

@@ -1,11 +0,0 @@
-gdbus_object_manager_example_doc = gnome.gtkdoc('gdbus-object-manager-example',
-  main_xml : 'gdbus-object-manager-example-docs.xml',
-  namespace : 'example',
-  dependencies : [libgdbus_example_objectmanager_dep],
-  src_dir : 'gio/tests/gdbus-object-manager-example',
-  scan_args : [
-    '--rebuild-types',
-  ],
-  install : false,
-)
-

docs/reference/gio/gdbus.rst

@@ -0,0 +1,278 @@
+.. _gdbus(1):
+.. meta::
+   :copyright: Copyright 2010, 2011, 2012, 2020 Red Hat, Inc.
+   :copyright: Copyright 2015 Collabora, Ltd.
+   :copyright: Copyright 2021 Endless OS Foundation, LLC
+   :license: LGPL-2.1-or-later
+..
+   This has to be duplicated from above to make it machine-readable by `reuse`:
+   SPDX-FileCopyrightText: 2010, 2011, 2012, 2020 Red Hat, Inc.
+   SPDX-FileCopyrightText: 2015 Collabora, Ltd.
+   SPDX-FileCopyrightText: 2021 Endless OS Foundation, LLC
+   SPDX-License-Identifier: LGPL-2.1-or-later
+
+=====
+gdbus
+=====
+
+-----------------------------------
+Tool for working with D-Bus objects
+-----------------------------------
+
+SYNOPSIS
+--------
+
+|  **gdbus** introspect [--system | --session | --address *address*] --dest *bus_name* --object-path */path/to/object* [--xml] [--recurse] [--only-properties]
+|  **gdbus** monitor [--system | --session | --address *address*] --dest *bus_name* [--object-path */path/to/object*]
+|  **gdbus** call [--system | --session | --address *address*] --dest *bus_name* --object-path */path/to/object* --method *org.project.InterfaceName.MethodName* [--timeout *seconds* | --interactive] [*ARG*…]
+|  **gdbus** emit [--system | --session | --address *address*] --object-path */path/to/object* --signal *org.project.InterfaceName.SignalName* [--dest *unique_bus_name*] [*ARG*…]
+|  **gdbus** wait [--system | --session | --address *address*] --activate *bus_name* [--timeout *seconds*] *bus_name*
+|  **gdbus** help
+
+DESCRIPTION
+-----------
+
+``gdbus`` is a simple tool for working with D-Bus objects.
+
+COMMANDS
+--------
+
+``introspect``
+
+  Prints out interfaces and property values for a remote object. For this to
+  work, the owner of the object needs to implement the
+  ``org.freedesktop.DBus.Introspectable`` interface. If the ``--xml`` option is
+  used, the returned introspection XML is printed, otherwise a parsed pretty
+  representation is printed. The ``--recurse`` option can be used to introspect
+  children (and their children and so on) and the ``--only-properties`` option
+  can be used to only print the interfaces with properties.
+
+``monitor``
+
+  Monitors one or all objects owned by the owner of ``bus_name``.
+
+``call``
+
+  Invokes a method on a remote object.  Each argument to pass to the method must
+  be specified as a serialized ``GVariant`` except that strings do not need
+  explicit quotes. The return values are printed out as serialized ``GVariant``
+  values.
+
+``emit``
+
+  Emits a signal. Each argument to include in the signal must be specified as a
+  serialized ``GVariant`` except that strings do not need explicit quotes.
+
+``wait``
+
+  Waits until ``bus_name`` is owned by some process on the bus. If the
+  ``--activate`` is specified, that bus name will be auto-started first. It may
+  be the same as the bus name being waited for, or different.
+
+``help``
+
+  Prints help and exits.
+
+BASH COMPLETION
+---------------
+
+``gdbus`` ships with a bash completion script to complete commands,
+destinations, bus names, object paths and interface/method names.
+
+EXAMPLES
+--------
+
+This shows how to introspect an object — note that the value of each property is
+displayed::
+
+   $ gdbus introspect --system \
+           --dest org.freedesktop.NetworkManager \
+           --object-path /org/freedesktop/NetworkManager/Devices/0
+   node /org/freedesktop/NetworkManager/Devices/0 {
+     interface org.freedesktop.DBus.Introspectable {
+       methods:
+         Introspect(out s data);
+     };
+     interface org.freedesktop.DBus.Properties {
+       methods:
+         Get(in  s interface,
+             in  s propname,
+             out v value);
+         Set(in  s interface,
+             in  s propname,
+             in  v value);
+         GetAll(in  s interface,
+                out a{sv} props);
+     };
+     interface org.freedesktop.NetworkManager.Device.Wired {
+       signals:
+         PropertiesChanged(a{sv} arg_0);
+       properties:
+         readonly b Carrier = false;
+         readonly u Speed = 0;
+         readonly s HwAddress = '00:1D:72:88:BE:97';
+     };
+     interface org.freedesktop.NetworkManager.Device {
+       methods:
+         Disconnect();
+       signals:
+         StateChanged(u arg_0,
+                      u arg_1,
+                      u arg_2);
+       properties:
+         readonly u DeviceType = 1;
+         readonly b Managed = true;
+         readwrite o Ip6Config = '/';
+         readwrite o Dhcp4Config = '/';
+         readwrite o Ip4Config = '/';
+         readonly u State = 2;
+         readwrite u Ip4Address = 0;
+         readonly u Capabilities = 3;
+         readonly s Driver = 'e1000e';
+         readwrite s Interface = 'eth0';
+         readonly s Udi = '/sys/devices/pci0000:00/0000:00:19.0/net/eth0';
+     };
+   };
+
+The ``--recurse`` and ``--only-properties`` options can be useful when wanting
+to inspect all objects owned by a particular process::
+
+   $ gdbus introspect --system --dest org.freedesktop.UPower --object-path / --recurse  --only-properties
+   node / {
+     node /org {
+       node /org/freedesktop {
+         node /org/freedesktop/UPower {
+           interface org.freedesktop.UPower {
+             properties:
+               readonly b IsDocked = true;
+               readonly b LidForceSleep = false;
+               readonly b LidIsPresent = false;
+               readonly b LidIsClosed = false;
+               readonly b OnLowBattery = false;
+               readonly b OnBattery = false;
+               readonly b CanHibernate = true;
+               readonly b CanSuspend = true;
+               readonly s DaemonVersion = '0.9.10';
+           };
+           node /org/freedesktop/UPower/Policy {
+           };
+           node /org/freedesktop/UPower/Wakeups {
+             interface org.freedesktop.UPower.Wakeups {
+               properties:
+                 readonly b HasCapability = true;
+             };
+           };
+         };
+       };
+     };
+   };
+
+In a similar fashion, the ``introspect`` command can be used to learn details
+about the ``Notify`` method::
+
+   […]
+     interface org.freedesktop.Notifications {
+       methods:
+         GetServerInformation(out s return_name,
+                              out s return_vendor,
+                              out s return_version,
+                              out s return_spec_version);
+         GetCapabilities(out as return_caps);
+         CloseNotification(in  u id);
+         Notify(in  s app_name,
+                in  u id,
+                in  s icon,
+                in  s summary,
+                in  s body,
+                in  as actions,
+                in  a{sv} hints,
+                in  i timeout,
+                out u return_id);
+     };
+   […]
+
+With this information, it’s easy to use the ``call`` command to display a
+notification::
+
+   $ gdbus call --session \
+                --dest org.freedesktop.Notifications \
+                --object-path /org/freedesktop/Notifications \
+                --method org.freedesktop.Notifications.Notify \
+                my_app_name \
+                42 \
+                gtk-dialog-info \
+                "The Summary" \
+                "Here’s the body of the notification" \
+                [] \
+                {} \
+                5000
+   (uint32 12,)
+
+Call a method with file handle argument::
+
+   $ gdbus call --session \
+                --dest org.example.foo \
+                --object-path /org/example/foo \
+                --method SendFDs \
+                1 \
+                10 \
+                10<file.foo
+
+Monitoring all objects on a service::
+
+   $ gdbus monitor --system --dest org.freedesktop.ConsoleKit
+   Monitoring signals from all objects owned by org.freedesktop.ConsoleKit
+   The name org.freedesktop.ConsoleKit is owned by :1.15
+   /org/freedesktop/ConsoleKit/Session2: org.freedesktop.ConsoleKit.Session.ActiveChanged (false,)
+   /org/freedesktop/ConsoleKit/Seat1: org.freedesktop.ConsoleKit.Seat.ActiveSessionChanged ('',)
+   /org/freedesktop/ConsoleKit/Session2: org.freedesktop.ConsoleKit.Session.ActiveChanged (true,)
+   /org/freedesktop/ConsoleKit/Seat1: org.freedesktop.ConsoleKit.Seat.ActiveSessionChanged ('/org/freedesktop/ConsoleKit/Session2',)
+
+Monitoring a single object on a service::
+
+   $ gdbus monitor --system --dest org.freedesktop.NetworkManager --object-path /org/freedesktop/NetworkManager/AccessPoint/4141
+   Monitoring signals on object /org/freedesktop/NetworkManager/AccessPoint/4141 owned by org.freedesktop.NetworkManager
+   The name org.freedesktop.NetworkManager is owned by :1.5
+   /org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': <byte 0x5c>},)
+   /org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': <byte 0x64>},)
+   /org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': <byte 0x5e>},)
+   /org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': <byte 0x64>},)
+
+Emitting a signal::
+
+   $ gdbus emit --session --object-path /foo --signal org.bar.Foo "['foo', 'bar', 'baz']"
+
+Emitting a signal to a specific process::
+
+   $ gdbus emit --session --object-path /bar --signal org.bar.Bar someString --dest :1.42
+
+Waiting for a well-known name to be owned on the bus; this will *not* auto-start
+the service::
+
+   $ gdbus wait --session org.bar.SomeName
+
+Auto-starting then waiting for a well-known name to be owned on the bus::
+
+   $ gdbus wait --session --activate org.bar.SomeName
+
+Auto-starting a different service, then waiting for a well-known name to be
+owned on the bus. This is useful in situations where ``SomeName`` is not
+directly activatable::
+
+   $ gdbus wait --session --activate org.bar.PrerequisiteName org.bar.SomeName
+
+Waiting for a well-known name and giving up after 30 seconds. By default, the
+timeout is disabled; or set ``--timeout`` to ``0`` to disable it::
+
+   $ gdbus wait --session --timeout 30 org.bar.SomeName
+
+BUGS
+----
+
+Please send bug reports to either the distribution bug tracker or the
+`upstream bug tracker <https://gitlab.gnome.org/GNOME/glib/issues/new>`_.
+
+SEE ALSO
+--------
+
+`dbus-send(1) <man:dbus-send(1)>`_

docs/reference/gio/gdbus.xml

@@ -1,429 +0,0 @@
-<refentry id="gdbus" lang="en">
-
-<refentryinfo>
-  <title>gdbus</title>
-  <productname>GIO</productname>
-  <authorgroup>
-    <author>
-      <contrib>Developer</contrib>
-      <firstname>David</firstname>
-      <surname>Zeuthen</surname>
-      <email>zeuthen@gmail.com</email>
-    </author>
-  </authorgroup>
-</refentryinfo>
-
-<refmeta>
-  <refentrytitle>gdbus</refentrytitle>
-  <manvolnum>1</manvolnum>
-  <refmiscinfo class="manual">User Commands</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-  <refname>gdbus</refname>
-  <refpurpose>Tool for working with D-Bus objects</refpurpose>
-</refnamediv>
-
-<refsynopsisdiv>
-  <cmdsynopsis>
-    <command>gdbus</command>
-    <arg choice="plain">introspect</arg>
-    <group>
-      <arg choice="plain">--system</arg>
-      <arg choice="plain">--session</arg>
-      <arg choice="plain">--address <replaceable>address</replaceable></arg>
-    </group>
-    <arg choice="plain">--dest <replaceable>bus_name</replaceable></arg>
-    <arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg>
-    <group>
-      <arg choice="plain">--xml</arg>
-    </group>
-    <group>
-      <arg choice="plain">--recurse</arg>
-    </group>
-    <group>
-      <arg choice="plain">--only-properties</arg>
-    </group>
-  </cmdsynopsis>
-  <cmdsynopsis>
-    <command>gdbus</command>
-    <arg choice="plain">monitor</arg>
-    <group>
-      <arg choice="plain">--system</arg>
-      <arg choice="plain">--session</arg>
-      <arg choice="plain">--address <replaceable>address</replaceable></arg>
-    </group>
-    <arg choice="plain">--dest <replaceable>bus_name</replaceable></arg>
-    <group>
-      <arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg>
-    </group>
-  </cmdsynopsis>
-  <cmdsynopsis>
-    <command>gdbus</command>
-    <arg choice="plain">call</arg>
-    <group>
-      <arg choice="plain">--system</arg>
-      <arg choice="plain">--session</arg>
-      <arg choice="plain">--address <replaceable>address</replaceable></arg>
-    </group>
-    <arg choice="plain">--dest <replaceable>bus_name</replaceable></arg>
-    <arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg>
-    <arg choice="plain">--method <replaceable>org.project.InterfaceName.MethodName</replaceable></arg>
-    <group>
-      <arg choice="plain">--timeout <replaceable>seconds</replaceable></arg>
-      <arg choice="plain">--interactive</arg>
-    </group>
-    <arg choice="plain">ARG1</arg>
-    <arg choice="plain" rep="repeat">ARG2</arg>
-  </cmdsynopsis>
-  <cmdsynopsis>
-    <command>gdbus</command>
-    <arg choice="plain">emit</arg>
-    <group>
-      <arg choice="plain">--system</arg>
-      <arg choice="plain">--session</arg>
-      <arg choice="plain">--address <replaceable>address</replaceable></arg>
-    </group>
-    <arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg>
-    <arg choice="plain">--signal <replaceable>org.project.InterfaceName.SignalName</replaceable></arg>
-    <group>
-      <arg choice="plain">--dest <replaceable>unique_bus_name</replaceable></arg>
-    </group>
-    <arg choice="plain">ARG1</arg>
-    <arg choice="plain" rep="repeat">ARG2</arg>
-  </cmdsynopsis>
-  <cmdsynopsis>
-    <command>gdbus</command>
-    <arg choice="plain">wait</arg>
-    <group>
-      <arg choice="plain">--system</arg>
-      <arg choice="plain">--session</arg>
-      <arg choice="plain">--address <replaceable>address</replaceable></arg>
-    </group>
-    <arg choice="plain">--activate <replaceable>bus_name</replaceable></arg>
-    <group>
-      <arg choice="plain">--timeout <replaceable>seconds</replaceable></arg>
-    </group>
-    <arg choice="plain"><replaceable>bus_name</replaceable></arg>
-  </cmdsynopsis>
-  <cmdsynopsis>
-    <command>gdbus</command>
-    <arg choice="plain">help</arg>
-  </cmdsynopsis>
-</refsynopsisdiv>
-
-<refsect1>
-  <title>Description</title>
-  <para>
-    <command>gdbus</command> is a simple tool for working with D-Bus objects.
-  </para>
-</refsect1>
-<refsect1>
-    <title>Commands</title>
-    <variablelist>
-      <varlistentry>
-        <term><option>introspect</option></term>
-        <listitem><para>
-          Prints out interfaces and property values for a remote object.
-          For this to work, the owner of the object needs to implement the
-          <literal>org.freedesktop.DBus.Introspectable</literal> interface.
-          If the <option>--xml</option> option is used, the returned
-          introspection XML is printed, otherwise a parsed pretty
-          representation is printed.
-          The <option>--recurse</option> option can be used to
-          introspect children (and their children and so on) and the
-          <option>--only-properties</option> option can be used to
-          only print the interfaces with properties.
-          </para></listitem>
-      </varlistentry>
-      <varlistentry>
-        <term><option>monitor</option></term>
-        <listitem><para>
-          Monitors one or all objects owned by the owner of
-          <replaceable>bus_name</replaceable>.
-        </para></listitem>
-      </varlistentry>
-      <varlistentry>
-        <term><option>call</option></term>
-        <listitem><para>
-          Invokes a method on a remote object.  Each argument to pass to the
-          method must be specified as a serialized
-          <link linkend="GVariant"><type>GVariant</type></link> except that strings do
-          not need explicit quotes. The return values are printed out as
-          serialized <link linkend="GVariant"><type>GVariant</type></link>
-          values.
-        </para></listitem>
-      </varlistentry>
-      <varlistentry>
-        <term><option>emit</option></term>
-        <listitem><para>
-          Emits a signal. Each argument to include in the signal must be specified as a serialized
-          <link linkend="GVariant"><type>GVariant</type></link> except that strings do
-          not need explicit quotes.
-        </para></listitem>
-      </varlistentry>
-      <varlistentry>
-        <term><option>wait</option></term>
-        <listitem><para>
-          Waits until <replaceable>bus_name</replaceable> is owned by some
-          process on the bus. If the <option>--activate</option> is specified,
-          that bus name will be auto-started first. It may be the same as the
-          bus name being waited for, or different.
-        </para></listitem>
-      </varlistentry>
-      <varlistentry>
-        <term><option>help</option></term>
-        <listitem><para>
-          Prints help and exit.
-        </para></listitem>
-      </varlistentry>
-    </variablelist>
-</refsect1>
-
-<refsect1>
-  <title>Bash Completion</title>
-  <para>
-    <command>gdbus</command> ships with a bash completion script to
-    complete commands, destinations, bus names, object paths and
-    interface/method names.
-  </para>
-</refsect1>
-
-<refsect1>
-  <title>Examples</title>
-  This shows how to introspect an object - note that the value of each
-  property is displayed:
-<programlisting>
-$ gdbus introspect --system \
-        --dest org.freedesktop.NetworkManager \
-        --object-path /org/freedesktop/NetworkManager/Devices/0
-node /org/freedesktop/NetworkManager/Devices/0 {
-  interface org.freedesktop.DBus.Introspectable {
-    methods:
-      Introspect(out s data);
-  };
-  interface org.freedesktop.DBus.Properties {
-    methods:
-      Get(in  s interface,
-          in  s propname,
-          out v value);
-      Set(in  s interface,
-          in  s propname,
-          in  v value);
-      GetAll(in  s interface,
-             out a{sv} props);
-  };
-  interface org.freedesktop.NetworkManager.Device.Wired {
-    signals:
-      PropertiesChanged(a{sv} arg_0);
-    properties:
-      readonly b Carrier = false;
-      readonly u Speed = 0;
-      readonly s HwAddress = '00:1D:72:88:BE:97';
-  };
-  interface org.freedesktop.NetworkManager.Device {
-    methods:
-      Disconnect();
-    signals:
-      StateChanged(u arg_0,
-                   u arg_1,
-                   u arg_2);
-    properties:
-      readonly u DeviceType = 1;
-      readonly b Managed = true;
-      readwrite o Ip6Config = '/';
-      readwrite o Dhcp4Config = '/';
-      readwrite o Ip4Config = '/';
-      readonly u State = 2;
-      readwrite u Ip4Address = 0;
-      readonly u Capabilities = 3;
-      readonly s Driver = 'e1000e';
-      readwrite s Interface = 'eth0';
-      readonly s Udi = '/sys/devices/pci0000:00/0000:00:19.0/net/eth0';
-  };
-};
-</programlisting>
-<para>
-  The <option>--recurse</option> and <option>--only-properties</option> options can be useful when wanting to inspect all objects owned by a particular process:
-</para>
-<programlisting>
-$ gdbus introspect --system --dest org.freedesktop.UPower --object-path / --recurse  --only-properties 
-node / {
-  node /org {
-    node /org/freedesktop {
-      node /org/freedesktop/UPower {
-        interface org.freedesktop.UPower {
-          properties:
-            readonly b IsDocked = true;
-            readonly b LidForceSleep = false;
-            readonly b LidIsPresent = false;
-            readonly b LidIsClosed = false;
-            readonly b OnLowBattery = false;
-            readonly b OnBattery = false;
-            readonly b CanHibernate = true;
-            readonly b CanSuspend = true;
-            readonly s DaemonVersion = '0.9.10';
-        };
-        node /org/freedesktop/UPower/Policy {
-        };
-        node /org/freedesktop/UPower/Wakeups {
-          interface org.freedesktop.UPower.Wakeups {
-            properties:
-              readonly b HasCapability = true;
-          };
-        };
-      };
-    };
-  };
-};
-</programlisting>
-<para>
-  In a similar fashion, the <option>introspect</option> command can be
-  used to learn details about the <literal>Notify</literal> method:
-</para>
-<programlisting>
-[...]
-  interface org.freedesktop.Notifications {
-    methods:
-      GetServerInformation(out s return_name,
-                           out s return_vendor,
-                           out s return_version,
-                           out s return_spec_version);
-      GetCapabilities(out as return_caps);
-      CloseNotification(in  u id);
-      Notify(in  s app_name,
-             in  u id,
-             in  s icon,
-             in  s summary,
-             in  s body,
-             in  as actions,
-             in  a{sv} hints,
-             in  i timeout,
-             out u return_id);
-  };
-[...]
-</programlisting>
-<para>
-  With this information, it's easy to use the <option>call</option>
-  command to display a notification
-</para>
-<programlisting>
-$ gdbus call --session \
-             --dest org.freedesktop.Notifications \
-             --object-path /org/freedesktop/Notifications \
-             --method org.freedesktop.Notifications.Notify \
-             my_app_name \
-             42 \
-             gtk-dialog-info \
-             "The Summary" \
-             "Here's the body of the notification" \
-             [] \
-             {} \
-             5000
-(uint32 12,)
-</programlisting>
-<para>
-  Call a method with file handle argument:
-</para>
-<programlisting>
-$ gdbus call --session \
-             --dest org.example.foo \
-             --object-path /org/example/foo \
-             --method SendFDs \
-             1 \
-             10 \
-             10&lt;file.foo
-</programlisting>
-<para>
-  Monitoring all objects on a service:
-</para>
-<programlisting>
-$ gdbus monitor --system --dest org.freedesktop.ConsoleKit
-Monitoring signals from all objects owned by org.freedesktop.ConsoleKit
-The name org.freedesktop.ConsoleKit is owned by :1.15
-/org/freedesktop/ConsoleKit/Session2: org.freedesktop.ConsoleKit.Session.ActiveChanged (false,)
-/org/freedesktop/ConsoleKit/Seat1: org.freedesktop.ConsoleKit.Seat.ActiveSessionChanged ('',)
-/org/freedesktop/ConsoleKit/Session2: org.freedesktop.ConsoleKit.Session.ActiveChanged (true,)
-/org/freedesktop/ConsoleKit/Seat1: org.freedesktop.ConsoleKit.Seat.ActiveSessionChanged ('/org/freedesktop/ConsoleKit/Session2',)
-</programlisting>
-<para>
-  Monitoring a single object on a service:
-</para>
-<programlisting>
-$ gdbus monitor --system --dest org.freedesktop.NetworkManager --object-path /org/freedesktop/NetworkManager/AccessPoint/4141
-Monitoring signals on object /org/freedesktop/NetworkManager/AccessPoint/4141 owned by org.freedesktop.NetworkManager
-The name org.freedesktop.NetworkManager is owned by :1.5
-/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': &lt;byte 0x5c&gt;},)
-/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': &lt;byte 0x64&gt;},)
-/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': &lt;byte 0x5e&gt;},)
-/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': &lt;byte 0x64&gt;},)
-</programlisting>
-
-<para>
-  Emitting a signal:
-</para>
-<programlisting>
-$ gdbus emit --session --object-path /foo --signal org.bar.Foo "['foo', 'bar', 'baz']"
-</programlisting>
-
-<para>
-  Emitting a signal to a specific process:
-</para>
-<programlisting>
-$ gdbus emit --session --object-path /bar --signal org.bar.Bar someString --dest :1.42
-</programlisting>
-
-<para>
-  Waiting for a well-known name to be owned on the bus; this will
-  <emphasis>not</emphasis> auto-start the service:
-</para>
-<programlisting>
-$ gdbus wait --session org.bar.SomeName
-</programlisting>
-
-<para>
-  Auto-starting then waiting for a well-known name to be owned on the bus:
-</para>
-<programlisting>
-$ gdbus wait --session --activate org.bar.SomeName
-</programlisting>
-
-<para>
-  Auto-starting a different service, then waiting for a well-known name to be
-  owned on the bus. This is useful in situations where
-  <replaceable>SomeName</replaceable> is not directly activatable:
-</para>
-<programlisting>
-$ gdbus wait --session --activate org.bar.PrerequisiteName org.bar.SomeName
-</programlisting>
-
-<para>
-  Waiting for a well-known name and giving up after 30 seconds. By default,
-  the timeout is disabled; or set <option>--timeout</option> to 0 to disable it:
-</para>
-<programlisting>
-$ gdbus wait --session --timeout 30 org.bar.SomeName
-</programlisting>
-
-</refsect1>
-
-<refsect1>
-  <title>Bugs</title>
-  <para>
-    Please send bug reports to either the distribution bug tracker
-    or the upstream bug tracker at
-    <ulink url="https://gitlab.gnome.org/GNOME/glib/issues/new"/>.
-  </para>
-</refsect1>
-
-<refsect1>
-  <title>See Also</title>
-  <para>
-    <citerefentry>
-      <refentrytitle>dbus-send</refentrytitle><manvolnum>1</manvolnum>
-    </citerefentry>
-  </para>
-</refsect1>
-
-</refentry>
-

docs/reference/gio/gio-docs-unix.xml

@@ -1,3 +0,0 @@
-<chapter id='unix-support'>
-<!--FIXME: fill this with unix APIs that cannot build on Windows -->
-</chapter>

docs/reference/gio/gio-docs-win32.xml

@@ -1,6 +0,0 @@
-<chapter id='win32-support'>
-    <title>Win32 support</title>
-    <xi:include href="xml/gwin32registrykey.xml"/>
-    <xi:include href="xml/gwin32inputstream.xml"/>
-    <xi:include href="xml/gwin32outputstream.xml"/>
-</chapter>

docs/reference/gio/gio-docs.xml

@@ -1,418 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
-                      'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [
-<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
-<!ENTITY version SYSTEM "version.xml">
-]>
-<book lang="en" id="gio" xmlns:xi="http://www.w3.org/2003/XInclude">
-<title>GIO Reference Manual</title>
-  <bookinfo>
-    <title>GIO Reference Manual</title>
-    <releaseinfo>
-      for GIO &version;
-      The latest version of this documentation can be found on-line at
-      <ulink role="online-location" url="https://developer.gnome.org/gio/unstable/">https://developer.gnome.org/gio/unstable/</ulink>.
-    </releaseinfo>
-  </bookinfo>
-
-  <xi:include href="xml/overview.xml"/>
-
-  <part>
-  <title>API Reference</title>
-    <chapter id="file_ops">
-        <title>File Operations</title>
-        <xi:include href="xml/gfile.xml"/>
-        <xi:include href="xml/gfileattribute.xml"/>
-        <xi:include href="xml/gfileinfo.xml"/>
-        <xi:include href="xml/gfileenumerator.xml"/>
-        <xi:include href="xml/gioerror.xml"/>
-        <xi:include href="xml/gmountoperation.xml"/>
-    </chapter>
-    <chapter id="file_mon">
-        <title>File System Monitoring</title>
-        <xi:include href="xml/gfilemonitor.xml"/>
-    </chapter>
-    <chapter id="utils">
-        <title>File-related Utilities</title>
-        <xi:include href="xml/gfilenamecompleter.xml"/>
-    </chapter>
-    <chapter id="async">
-        <title>Asynchronous I/O</title>
-        <xi:include href="xml/gcancellable.xml"/>
-        <xi:include href="xml/gasyncresult.xml"/>
-        <xi:include href="xml/gtask.xml"/>
-        <xi:include href="xml/gioscheduler.xml"/>
-        <xi:include href="xml/gsimpleasyncresult.xml"/>
-    </chapter>
-    <chapter id="conversion">
-        <title>Data conversion</title>
-        <xi:include href="xml/gconverter.xml"/>
-        <xi:include href="xml/gcharsetconverter.xml"/>
-        <xi:include href="xml/gzlibcompressor.xml"/>
-        <xi:include href="xml/gzlibdecompressor.xml"/>
-    </chapter>
-    <chapter id="streaming">
-        <title>Streaming I/O</title>
-        <xi:include href="xml/gseekable.xml"/>
-        <xi:include href="xml/ginputstream.xml"/>
-        <xi:include href="xml/goutputstream.xml"/>
-        <xi:include href="xml/giostream.xml"/>
-        <xi:include href="xml/gsimpleiostream.xml"/>
-        <xi:include href="xml/gfileinputstream.xml"/>
-        <xi:include href="xml/gfileoutputstream.xml"/>
-        <xi:include href="xml/gfileiostream.xml"/>
-        <xi:include href="xml/gfiledescriptorbased.xml"/>
-        <xi:include href="xml/gfilterinputstream.xml"/>
-        <xi:include href="xml/gfilteroutputstream.xml"/>
-        <xi:include href="xml/gmemoryinputstream.xml"/>
-        <xi:include href="xml/gmemoryoutputstream.xml"/>
-        <xi:include href="xml/gbufferedinputstream.xml"/>
-        <xi:include href="xml/gbufferedoutputstream.xml"/>
-        <xi:include href="xml/gdatainputstream.xml"/>
-        <xi:include href="xml/gdataoutputstream.xml"/>
-        <xi:include href="xml/gunixinputstream.xml"/>
-        <xi:include href="xml/gunixoutputstream.xml"/>
-        <xi:include href="xml/gconverterinputstream.xml"/>
-        <xi:include href="xml/gconverteroutputstream.xml"/>
-        <xi:include href="xml/gpollableinputstream.xml"/>
-        <xi:include href="xml/gpollableoutputstream.xml"/>
-        <xi:include href="xml/gpollableutils.xml"/>
-    </chapter>
-    <chapter id="types">
-        <title>File types and applications</title>
-        <xi:include href="xml/gcontenttype.xml"/>
-        <xi:include href="xml/gappinfo.xml"/>
-        <xi:include href="xml/gappinfomonitor.xml"/>
-        <xi:include href="xml/gdesktopappinfo.xml"/>
-    </chapter>
-    <chapter id="volume_mon">
-        <title>Volumes and Drives</title>
-        <xi:include href="xml/gvolumemonitor.xml"/>
-        <xi:include href="xml/gvolume.xml"/>
-        <xi:include href="xml/gmount.xml"/>
-        <xi:include href="xml/gdrive.xml"/>
-        <xi:include href="xml/gunixmounts.xml"/>
-    </chapter>
-    <chapter id="icons">
-        <title>Icons</title>
-        <xi:include href="xml/gicon.xml"/>
-        <xi:include href="xml/gfileicon.xml"/>
-        <xi:include href="xml/gbytesicon.xml"/>
-        <xi:include href="xml/gloadableicon.xml"/>
-        <xi:include href="xml/gthemedicon.xml"/>
-        <xi:include href="xml/gemblemedicon.xml"/>
-        <xi:include href="xml/gemblem.xml"/>
-    </chapter>
-    <chapter id="failable_initialization">
-        <title>Failable Initialization</title>
-        <xi:include href="xml/ginitable.xml"/>
-        <xi:include href="xml/gasyncinitable.xml"/>
-    </chapter>
-    <chapter id="subprocesses">
-      <title>Subprocesses</title>
-      <xi:include href="xml/gsubprocess.xml"/>
-      <xi:include href="xml/gsubprocesslauncher.xml"/>
-    </chapter>
-    <chapter id="networking">
-      <title>Low-level network support</title>
-      <xi:include href="xml/gsocket.xml"/>
-      <xi:include href="xml/gdatagrambased.xml"/>
-      <xi:include href="xml/ginetaddress.xml"/>
-      <xi:include href="xml/ginetaddressmask.xml"/>
-      <xi:include href="xml/gsocketaddress.xml"/>
-      <xi:include href="xml/ginetsocketaddress.xml"/>
-      <xi:include href="xml/gunixsocketaddress.xml"/>
-      <xi:include href="xml/gnativesocketaddress.xml"/>
-      <xi:include href="xml/gsocketcontrolmessage.xml"/>
-      <xi:include href="xml/gunixfdlist.xml"/>
-      <xi:include href="xml/gunixfdmessage.xml"/>
-      <xi:include href="xml/gcredentials.xml"/>
-      <xi:include href="xml/gunixcredentialsmessage.xml"/>
-      <xi:include href="xml/gproxy.xml"/>
-      <xi:include href="xml/gproxyaddress.xml"/>
-      <xi:include href="xml/gnetworking.xml"/>
-    </chapter>
-    <chapter id="highlevel-socket">
-      <title>High-level network functionality</title>
-      <xi:include href="xml/gsocketclient.xml"/>
-      <xi:include href="xml/gsocketconnection.xml"/>
-      <xi:include href="xml/gunixconnection.xml"/>
-      <xi:include href="xml/gtcpconnection.xml"/>
-      <xi:include href="xml/gtcpwrapperconnection.xml"/>
-      <xi:include href="xml/gsocketlistener.xml"/>
-      <xi:include href="xml/gsocketservice.xml"/>
-      <xi:include href="xml/gthreadedsocketservice.xml"/>
-      <xi:include href="xml/gnetworkmonitor.xml"/>
-    </chapter>
-    <chapter id="tls">
-      <title>TLS (SSL) support</title>
-      <xi:include href="xml/gtls.xml"/>
-      <xi:include href="xml/gtlscertificate.xml"/>
-      <xi:include href="xml/gtlsconnection.xml"/>
-      <xi:include href="xml/gtlsclientconnection.xml"/>
-      <xi:include href="xml/gtlsserverconnection.xml"/>
-      <xi:include href="xml/gdtlsconnection.xml"/>
-      <xi:include href="xml/gdtlsclientconnection.xml"/>
-      <xi:include href="xml/gdtlsserverconnection.xml"/>
-      <xi:include href="xml/gtlsbackend.xml"/>
-      <xi:include href="xml/gtlsdatabase.xml"/>
-      <xi:include href="xml/gtlsfiledatabase.xml"/>
-      <xi:include href="xml/gtlsinteraction.xml"/>
-      <xi:include href="xml/gtlspassword.xml"/>
-    </chapter>
-    <chapter id="resolver">
-      <title>DNS resolution</title>
-      <xi:include href="xml/gresolver.xml"/>
-      <xi:include href="xml/gproxyresolver.xml"/>
-      <xi:include href="xml/gsimpleproxyresolver.xml"/>
-      <xi:include href="xml/gsocketconnectable.xml"/>
-      <xi:include href="xml/gsocketaddressenumerator.xml"/>
-      <xi:include href="xml/gproxyaddressenumerator.xml"/>
-      <xi:include href="xml/gnetworkaddress.xml"/>
-      <xi:include href="xml/gnetworkservice.xml"/>
-      <xi:include href="xml/gsrvtarget.xml"/>
-    </chapter>
-    <chapter id="gdbus-lowlevel">
-      <title>Low-level D-Bus Support</title>
-      <xi:include href="xml/gdbusutils.xml"/>
-      <xi:include href="xml/gdbusaddress.xml"/>
-      <xi:include href="xml/gdbusintrospection.xml"/>
-      <xi:include href="xml/gdbuserror.xml"/>
-      <xi:include href="xml/gdbusmessage.xml"/>
-      <xi:include href="xml/gdbusconnection.xml"/>
-      <xi:include href="xml/gdbusmethodinvocation.xml"/>
-      <xi:include href="xml/gdbusserver.xml"/>
-      <xi:include href="xml/gdbusauthobserver.xml"/>
-    </chapter>
-    <chapter id="gdbus-convenience">
-      <title>High-level D-Bus Support</title>
-      <xi:include href="xml/gdbusnameowning.xml"/>
-      <xi:include href="xml/gdbusnamewatching.xml"/>
-      <xi:include href="xml/gdbusinterface.xml"/>
-      <xi:include href="xml/gdbusinterfaceskeleton.xml"/>
-      <xi:include href="xml/gdbusproxy.xml"/>
-      <xi:include href="xml/gdbusobject.xml"/>
-      <xi:include href="xml/gdbusobjectskeleton.xml"/>
-      <xi:include href="xml/gdbusobjectproxy.xml"/>
-      <xi:include href="xml/gdbusobjectmanager.xml"/>
-      <xi:include href="xml/gdbusobjectmanagerserver.xml"/>
-      <xi:include href="xml/gdbusobjectmanagerclient.xml"/>
-    </chapter>
-    <chapter id="settings">
-        <title>Settings</title>
-        <xi:include href="xml/gsettings.xml"/>
-        <xi:include href="xml/gsettingsbackend.xml"/>
-        <xi:include href="xml/gsettingsschema.xml"/>
-    </chapter>
-    <chapter id="resources">
-        <title>Resources</title>
-        <xi:include href="xml/gresource.xml"/>
-    </chapter>
-    <chapter id='permissions'>
-        <title>Permissions</title>
-        <xi:include href="xml/gpermission.xml"/>
-        <xi:include href="xml/gsimplepermission.xml"/>
-    </chapter>
-    <chapter id='data-models'>
-        <title>Data Models</title>
-        <xi:include href="xml/glistmodel.xml"/>
-        <xi:include href="xml/gliststore.xml"/>
-    </chapter>
-
-    <chapter id="application">
-        <title>Application support</title>
-        <xi:include href="xml/gapplication.xml"/>
-        <xi:include href="xml/gapplicationcommandline.xml"/>
-        <xi:include href="xml/gactiongroup.xml"/>
-        <xi:include href="xml/gactionmap.xml"/>
-        <xi:include href="xml/gsimpleactiongroup.xml"/>
-        <xi:include href="xml/gaction.xml"/>
-        <xi:include href="xml/gsimpleaction.xml"/>
-        <xi:include href="xml/gpropertyaction.xml"/>
-        <xi:include href="xml/gremoteactiongroup.xml"/>
-        <xi:include href="xml/gactiongroupexporter.xml"/>
-        <xi:include href="xml/gdbusactiongroup.xml"/>
-        <xi:include href="xml/gdebugcontroller.xml"/>
-        <xi:include href="xml/gdebugcontrollerdbus.xml"/>
-        <xi:include href="xml/gmemorymonitor.xml"/>
-        <xi:include href="xml/gmenumodel.xml"/>
-        <xi:include href="xml/gmenu.xml"/>
-        <xi:include href="xml/gmenuexporter.xml"/>
-        <xi:include href="xml/gdbusmenumodel.xml"/>
-        <xi:include href="xml/gnotification.xml"/>
-        <xi:include href="xml/gpowerprofilemonitor.xml"/>
-    </chapter>
-    <chapter id="extending">
-        <title>Extending GIO</title>
-        <xi:include href="xml/gvfs.xml"/>
-        <xi:include href="xml/giomodule.xml"/>
-        <xi:include href="xml/extensionpoints.xml"/>
-    </chapter>
-    <chapter id="tools">
-        <title>GIO Tools</title>
-        <xi:include href="gio-querymodules.xml"/>
-        <xi:include href="gsettings.xml"/>
-        <xi:include href="glib-compile-schemas.xml"/>
-        <xi:include href="glib-compile-resources.xml"/>
-        <xi:include href="gdbus.xml"/>
-        <xi:include href="xml/gdbus-codegen.xml"/>
-        <xi:include href="gresource.xml"/>
-        <xi:include href="gapplication.xml"/>
-        <xi:include href="gio.xml"/>
-    </chapter>
-    <chapter id="testing">
-        <title>GIO Testing</title>
-        <xi:include href="xml/gtestdbus.xml"/>
-    </chapter>
-    <xi:include href="gio-docs-platform.xml"/>
-  </part>
-
-  <part id="migrating">
-    <title>Migrating to GIO</title>
-    <xi:include href="xml/migrating-posix.xml"/>
-    <xi:include href="xml/migrating-gnome-vfs.xml"/>
-    <xi:include href="xml/migrating-gconf.xml"/>
-    <xi:include href="xml/migrating-gdbus.xml"/>
-  </part>
-
-  <chapter id="gio-hierarchy">
-    <title>Object Hierarchy</title>
-      <xi:include href="xml/tree_index.sgml"/>
-  </chapter>
-  
-  <chapter id="api-index-full">
-    <title id="index-all">Index</title>
-    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
-  </chapter>
-  <chapter id="api-index-deprecated" role="deprecated">
-    <title>Index of deprecated symbols</title>
-    <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
-  </chapter>
-  <chapter id="api-index-2-18" role="2.18">
-    <title>Index of new symbols in 2.18</title>
-    <xi:include href="xml/api-index-2.18.xml"><xi:fallback /></xi:include>
-  </chapter>
-  <chapter id="api-index-2-20" role="2.20">
-    <title>Index of new symbols in 2.20</title>
-    <xi:include href="xml/api-index-2.20.xml"><xi:fallback /></xi:include>
-  </chapter>
-  <chapter id="api-index-2-22" role="2.22">
-    <title>Index of new symbols in 2.22</title>
-    <xi:include href="xml/api-index-2.22.xml"><xi:fallback /></xi:include>
-  </chapter>
-  <chapter id="api-index-2-24" role="2.24">
-    <title>Index of new symbols in 2.24</title>
-    <xi:include href="xml/api-index-2.24.xml"><xi:fallback /></xi:include>
-  </chapter>
-  <chapter id="api-index-2-26" role="2.26">
-    <title>Index of new symbols in 2.26</title>
-    <xi:include href="xml/api-index-2.26.xml"><xi:fallback /></xi:include>
-  </chapter>
-  <chapter id="api-index-2-28" role="2.28">
-    <title>Index of new symbols in 2.28</title>
-    <xi:include href="xml/api-index-2.28.xml"><xi:fallback /></xi:include>
-  </chapter>
-  <chapter id="api-index-2-30" role="2.30">
-    <title>Index of new symbols in 2.30</title>
-    <xi:include href="xml/api-index-2.30.xml"><xi:fallback /></xi:include>
-  </chapter>
-  <chapter id="api-index-2-32" role="2.32">
-    <title>Index of new symbols in 2.32</title>
-    <xi:include href="xml/api-index-2.32.xml"><xi:fallback /></xi:include>
-  </chapter>
-  <chapter id="api-index-2-34" role="2.34">
-    <title>Index of new symbols in 2.34</title>
-    <xi:include href="xml/api-index-2.34.xml"><xi:fallback /></xi:include>
-  </chapter>
-  <chapter id="api-index-2-36" role="2.36">
-    <title>Index of new symbols in 2.36</title>
-    <xi:include href="xml/api-index-2.36.xml"><xi:fallback /></xi:include>
-  </chapter>
-  <chapter id="api-index-2-38" role="2.38">
-    <title>Index of new symbols in 2.38</title>
-    <xi:include href="xml/api-index-2.38.xml"><xi:fallback /></xi:include>
-  </chapter>
-  <chapter id="api-index-2-40" role="2.40">
-    <title>Index of new symbols in 2.40</title>
-    <xi:include href="xml/api-index-2.40.xml"><xi:fallback /></xi:include>
-  </chapter>
-  <chapter id="api-index-2-42" role="2.42">
-    <title>Index of new symbols in 2.42</title>
-    <xi:include href="xml/api-index-2.42.xml"><xi:fallback /></xi:include>
-  </chapter>
-  <chapter id="api-index-2-44" role="2.44">
-    <title>Index of new symbols in 2.44</title>
-    <xi:include href="xml/api-index-2.44.xml"><xi:fallback /></xi:include>
-  </chapter>
-  <chapter id="api-index-2-46" role="2.46">
-    <title>Index of new symbols in 2.46</title>
-    <xi:include href="xml/api-index-2.46.xml"><xi:fallback /></xi:include>
-  </chapter>
-  <chapter id="api-index-2-48" role="2.48">
-    <title>Index of new symbols in 2.48</title>
-    <xi:include href="xml/api-index-2.48.xml"><xi:fallback /></xi:include>
-  </chapter>
-  <chapter id="api-index-2-50" role="2.50">
-    <title>Index of new symbols in 2.50</title>
-    <xi:include href="xml/api-index-2.50.xml"><xi:fallback /></xi:include>
-  </chapter>
-  <chapter id="api-index-2-52" role="2.52">
-    <title>Index of new symbols in 2.52</title>
-    <xi:include href="xml/api-index-2.52.xml"><xi:fallback /></xi:include>
-  </chapter>
-  <chapter id="api-index-2-54" role="2.54">
-    <title>Index of new symbols in 2.54</title>
-    <xi:include href="xml/api-index-2.54.xml"><xi:fallback /></xi:include>
-  </chapter>
-  <chapter id="api-index-2-56" role="2.56">
-    <title>Index of new symbols in 2.56</title>
-    <xi:include href="xml/api-index-2.56.xml"><xi:fallback /></xi:include>
-  </chapter>
-  <chapter id="api-index-2-58" role="2.58">
-    <title>Index of new symbols in 2.58</title>
-    <xi:include href="xml/api-index-2.58.xml"><xi:fallback /></xi:include>
-  </chapter>
-  <chapter id="api-index-2-60" role="2.60">
-    <title>Index of new symbols in 2.60</title>
-    <xi:include href="xml/api-index-2.60.xml"><xi:fallback /></xi:include>
-  </chapter>
-  <chapter id="api-index-2-62" role="2.62">
-    <title>Index of new symbols in 2.62</title>
-    <xi:include href="xml/api-index-2.62.xml"><xi:fallback /></xi:include>
-  </chapter>
-  <chapter id="api-index-2-64" role="2.64">
-    <title>Index of new symbols in 2.64</title>
-    <xi:include href="xml/api-index-2.64.xml"><xi:fallback /></xi:include>
-  </chapter>
-  <chapter id="api-index-2-66" role="2.66">
-    <title>Index of new symbols in 2.66</title>
-    <xi:include href="xml/api-index-2.66.xml"><xi:fallback /></xi:include>
-  </chapter>
-  <chapter id="api-index-2-68" role="2.68">
-    <title>Index of new symbols in 2.68</title>
-    <xi:include href="xml/api-index-2.68.xml"><xi:fallback /></xi:include>
-  </chapter>
-  <chapter id="api-index-2-70" role="2.70">
-    <title>Index of new symbols in 2.70</title>
-    <xi:include href="xml/api-index-2.70.xml"><xi:fallback /></xi:include>
-  </chapter>
-  <chapter id="api-index-2-72" role="2.72">
-    <title>Index of new symbols in 2.72</title>
-    <xi:include href="xml/api-index-2.72.xml"><xi:fallback /></xi:include>
-  </chapter>
-  <chapter id="api-index-2-74" role="2.74">
-    <title>Index of new symbols in 2.74</title>
-    <xi:include href="xml/api-index-2.74.xml"><xi:fallback /></xi:include>
-  </chapter>
-  <chapter id="api-index-2-76" role="2.76">
-    <title>Index of new symbols in 2.76</title>
-    <xi:include href="xml/api-index-2.76.xml"><xi:fallback /></xi:include>
-  </chapter>
-  <chapter id="api-index-2-78" role="2.78">
-    <title>Index of new symbols in 2.78</title>
-    <xi:include href="xml/api-index-2.78.xml"><xi:fallback /></xi:include>
-  </chapter>
-
-  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
-
-</book>

docs/reference/gio/gio-querymodules.rst

@@ -0,0 +1,31 @@
+.. _gio-querymodules(1):
+.. meta::
+   :copyright: Copyright 2010, 2012 Red Hat, Inc.
+   :license: LGPL-2.1-or-later
+..
+   This has to be duplicated from above to make it machine-readable by `reuse`:
+   SPDX-FileCopyrightText: 2010, 2012 Red Hat, Inc.
+   SPDX-License-Identifier: LGPL-2.1-or-later
+
+================
+gio-querymodules
+================
+
+-------------------------
+GIO module cache creation
+-------------------------
+
+SYNOPSIS
+--------
+
+|  **gio-querymodules** *DIRECTORY*…
+
+DESCRIPTION
+-----------
+
+``gio-querymodules`` creates a ``giomodule.cache`` file in the listed
+directories. This file lists the implemented extension points for each module
+that has been found. It is used by GIO at runtime to avoid opening all modules
+just to find out which extension points they are implementing.
+
+GIO modules are usually installed in the ``gio/modules`` subdirectory of libdir.

docs/reference/gio/gio-querymodules.xml

@@ -1,45 +0,0 @@
-<refentry id="gio-querymodules" lang="en">
-
-<refentryinfo>
-  <title>glib-compile-schemas</title>
-  <productname>GIO</productname>
-  <authorgroup>
-    <author>
-      <contrib>Developer</contrib>
-      <firstname>Alexander</firstname>
-      <surname>Larsson</surname>
-    </author>
-  </authorgroup>
-</refentryinfo>
-
-<refmeta>
-  <refentrytitle>gio-querymodules</refentrytitle>
-  <manvolnum>1</manvolnum>
-  <refmiscinfo class="manual">User Commands</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-  <refname>gio-querymodules</refname>
-  <refpurpose>GIO module cache creation</refpurpose>
-</refnamediv>
-
-<refsynopsisdiv>
-  <cmdsynopsis>
-    <command>gio-querymodules</command>
-    <arg choice="req" rep="repeat">DIRECTORY</arg>
-  </cmdsynopsis>
-</refsynopsisdiv>
-
-<refsect1><title>Description</title>
-<para><command>gio-querymodules</command> creates a
-<filename>giomodule.cache</filename> file in the listed directories.
-This file lists the implemented extension points for each module
-that has been found. It is used by GIO at runtime to avoid opening
-all modules just to find out which extension points they are implementing.
-</para>
-<para>
-GIO modules are usually installed in the <filename>gio/modules</filename>
-subdirectory of libdir.
-</para>
-</refsect1>
-</refentry>

docs/reference/gio/gio-sections-win32.txt

@@ -1,122 +0,0 @@
-<SECTION>
-<FILE>gwin32inputstream</FILE>
-<TITLE>GWin32InputStream</TITLE>
-GWin32InputStream
-g_win32_input_stream_new
-g_win32_input_stream_set_close_handle
-g_win32_input_stream_get_close_handle
-g_win32_input_stream_get_handle
-<SUBSECTION Standard>
-GWin32InputStreamClass
-G_WIN32_INPUT_STREAM
-G_IS_WIN32_INPUT_STREAM
-G_TYPE_WIN32_INPUT_STREAM
-G_WIN32_INPUT_STREAM_CLASS
-G_IS_WIN32_INPUT_STREAM_CLASS
-G_WIN32_INPUT_STREAM_GET_CLASS
-<SUBSECTION Private>
-g_win32_input_stream_get_type
-GWin32InputStreamPrivate
-</SECTION>
-
-<SECTION>
-<FILE>gwin32outputstream</FILE>
-<TITLE>GWin32OutputStream</TITLE>
-GWin32OutputStream
-g_win32_output_stream_new
-g_win32_output_stream_set_close_handle
-g_win32_output_stream_get_close_handle
-g_win32_output_stream_get_handle
-<SUBSECTION Standard>
-GWin32OutputStreamClass
-G_WIN32_OUTPUT_STREAM
-G_IS_WIN32_OUTPUT_STREAM
-G_TYPE_WIN32_OUTPUT_STREAM
-G_WIN32_OUTPUT_STREAM_CLASS
-G_IS_WIN32_OUTPUT_STREAM_CLASS
-G_WIN32_OUTPUT_STREAM_GET_CLASS
-<SUBSECTION Private>
-g_win32_output_stream_get_type
-GWin32OutputStreamPrivate
-</SECTION>
-
-<SECTION>
-<FILE>gwin32registrykey</FILE>
-
-<SUBSECTION>
-GWin32RegistrySubkeyIter
-g_win32_registry_subkey_iter_copy
-g_win32_registry_subkey_iter_free
-g_win32_registry_subkey_iter_assign
-
-<SUBSECTION>
-GWin32RegistryValueIter
-g_win32_registry_value_iter_copy
-g_win32_registry_value_iter_free
-g_win32_registry_value_iter_assign
-
-<SUBSECTION>
-GWin32RegistryKey
-g_win32_registry_key_new
-g_win32_registry_key_new_w
-g_win32_registry_key_get_child
-g_win32_registry_key_get_child_w
-
-<SUBSECTION>
-g_win32_registry_subkey_iter_init
-g_win32_registry_subkey_iter_clear
-g_win32_registry_subkey_iter_n_subkeys
-g_win32_registry_subkey_iter_next
-g_win32_registry_subkey_iter_get_name
-g_win32_registry_subkey_iter_get_name_w
-
-<SUBSECTION>
-g_win32_registry_value_iter_init
-g_win32_registry_value_iter_clear
-g_win32_registry_value_iter_n_values
-g_win32_registry_value_iter_next
-GWin32RegistryValueType
-g_win32_registry_value_iter_get_value_type
-g_win32_registry_value_iter_get_name
-g_win32_registry_value_iter_get_name_w
-g_win32_registry_value_iter_get_data
-g_win32_registry_value_iter_get_data_w
-
-<SUBSECTION>
-g_win32_registry_key_get_value
-g_win32_registry_key_get_value_w
-g_win32_registry_key_get_path
-g_win32_registry_key_get_path_w
-GWin32RegistryKeyWatchCallbackFunc
-GWin32RegistryKeyWatcherFlags
-g_win32_registry_key_watch
-g_win32_registry_key_has_changed
-g_win32_registry_key_erase_change_indicator
-
-<SUBSECTION Standard>
-GWin32RegistryKeyClass
-
-<SUBSECTION Private>
-GWin32RegistryKeyPrivate
-g_win32_registry_key_get_type
-g_win32_registry_subkey_iter_get_type
-g_win32_registry_value_iter_get_type
-G_TYPE_WIN32_REGISTRY_KEY
-G_WIN32_REGISTRY_KEY
-G_WIN32_REGISTRY_KEY_CLASS
-G_IS_WIN32_REGISTRY_KEY
-G_IS_WIN32_REGISTRY_KEY_CLASS
-G_WIN32_REGISTRY_KEY_GET_CLASS
-G_TYPE_WIN32_REGISTRY_SUBKEY_ITER
-G_TYPE_WIN32_REGISTRY_VALUE_ITER
-</SECTION>
-
-<SECTION>
-<FILE>gregistrysettingsbackend</FILE>
-<TITLE>GRegistrySettingsBackend</TITLE>
-GRegistrySettingsBackend
-g_registry_settings_backend_new
-
-<SUBSECTION Private>
-g_registry_settings_backend_get_type
-</SECTION>

docs/reference/gio/gio-unix.toml.in

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: LGPL-2.1-or-later
+# Copyright 2023 Matthias Clasen
+# Copyright 2023 Philip Withnall
+
+[library]
+name = "GioUnix"
+version = "@VERSION@"
+browse_url = "https://gitlab.gnome.org/GNOME/glib/"
+repository_url = "https://gitlab.gnome.org/GNOME/glib.git"
+website_url = "https://www.gtk.org"
+docs_urls = "https://docs.gtk.org/gio-unix/"
+authors = "GLib Development Team"
+license = "LGPL-2.1-or-later"
+description = "Unix-specific APIs in Gio"
+dependencies = [ "GLib-2.0", "GModule-2.0", "GObject-2.0", "Gio-2.0" ]
+devhelp = true
+search_index = true
+
+  [dependencies."GLib-2.0"]
+  name = "GLib"
+  description = "The base utility library"
+  docs_url = "https://docs.gtk.org/glib/"
+
+  [dependencies."GModule-2.0"]
+  name = "GModule"
+  description = "Portable API for dynamically loading modules"
+  docs_url = "https://docs.gtk.org/gmodule/"
+
+  [dependencies."GObject-2.0"]
+  name = "GObject"
+  description = "The base type system library"
+  docs_url = "https://docs.gtk.org/gobject/"
+
+  [dependencies."Gio-2.0"]
+  name = "Gio"
+  description = "A library of useful classes for I/O, networking and IPC"
+  docs_url = "https://docs.gtk.org/gio/"
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[extra]
+urlmap_file = "../urlmap.js"
+# The same order will be used when generating the index
+content_files = [
+  "unix-mounts.md",
+]
+content_images = []

docs/reference/gio/gio-win32.toml.in

@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: LGPL-2.1-or-later
+# Copyright 2023 Matthias Clasen
+# Copyright 2023 Philip Withnall
+
+[library]
+name = "GioWin32"
+version = "@VERSION@"
+browse_url = "https://gitlab.gnome.org/GNOME/glib/"
+repository_url = "https://gitlab.gnome.org/GNOME/glib.git"
+website_url = "https://www.gtk.org"
+docs_urls = "https://docs.gtk.org/gio-win32/"
+authors = "GLib Development Team"
+license = "LGPL-2.1-or-later"
+description = "Windows-specific APIs in Gio"
+dependencies = [ "GLib-2.0", "GModule-2.0", "GObject-2.0", "Gio-2.0" ]
+devhelp = true
+search_index = true
+
+  [dependencies."GLib-2.0"]
+  name = "GLib"
+  description = "The base utility library"
+  docs_url = "https://docs.gtk.org/glib/"
+
+  [dependencies."GModule-2.0"]
+  name = "GModule"
+  description = "Portable API for dynamically loading modules"
+  docs_url = "https://docs.gtk.org/gmodule/"
+
+  [dependencies."GObject-2.0"]
+  name = "GObject"
+  description = "The base type system library"
+  docs_url = "https://docs.gtk.org/gobject/"
+
+  [dependencies."Gio-2.0"]
+  name = "Gio"
+  description = "A library of useful classes for I/O, networking and IPC"
+  docs_url = "https://docs.gtk.org/gio/"
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[extra]
+urlmap_file = "../urlmap.js"
+# The same order will be used when generating the index
+content_files = []
+content_images = []

docs/reference/gio/gio.rst

@@ -0,0 +1,528 @@
+.. _gio(1):
+.. meta::
+   :copyright: Copyright 2015, 2019, 2020 Red Hat, Inc.
+   :copyright: Copyright 2018, 2019 Endless Mobile, Inc.
+   :copyright: Copyright 2018 segfault
+   :copyright: Copyright 2020 Frederic Martinsons
+   :copyright: Copyright 2022 Marco Trevisan
+   :license: LGPL-2.1-or-later
+..
+   This has to be duplicated from above to make it machine-readable by `reuse`:
+   SPDX-FileCopyrightText: 2015, 2019, 2020 Red Hat, Inc.
+   SPDX-FileCopyrightText: 2018, 2019 Endless Mobile, Inc.
+   SPDX-FileCopyrightText: 2018 segfault
+   SPDX-FileCopyrightText: 2020 Frederic Martinsons
+   SPDX-FileCopyrightText: 2022 Marco Trevisan
+   SPDX-License-Identifier: LGPL-2.1-or-later
+
+===
+gio
+===
+
+--------------------
+GIO commandline tool
+--------------------
+
+SYNOPSIS
+--------
+
+|  **gio** help [*COMMAND*]
+|  **gio** version
+|  **gio** cat *LOCATION*…
+|  **gio** copy [*OPTION*…] *SOURCE*… *DESTINATION*
+|  **gio** info [*OPTION*…] *LOCATION*…
+|  **gio** launch *DESKTOP-FILE* [*FILE-ARG*…]
+|  **gio** list [*OPTION*…] [*LOCATION*…]
+|  **gio** mime *MIME-TYPE* [*HANDLER*]
+|  **gio** mkdir [*OPTION*…] *LOCATION*…
+|  **gio** monitor [*OPTION*…] [*LOCATION*…]
+|  **gio** mount [*OPTION*…] [*LOCATION*…]
+|  **gio** move [*OPTION*…] *SOURCE*… *DESTINATION*
+|  **gio** open *LOCATION*…
+|  **gio** rename *LOCATION* *NAME*
+|  **gio** remove [*OPTION*…] *LOCATION*…
+|  **gio** save [*OPTION*…] *DESTINATION*
+|  **gio** set [*OPTION*…] *LOCATION* *ATTRIBUTE* *VALUE*…
+|  **gio** trash [*OPTION*…] [*LOCATION*…]
+|  **gio** tree [*OPTION*…] [*LOCATION*…]
+
+DESCRIPTION
+-----------
+
+``gio`` is a utility that makes many of the GIO features available from the
+commandline. In doing so, it provides commands that are similar to traditional
+utilities, but let you use GIO locations instead of local files: for example you
+can use something like ``smb://server/resource/file.txt`` as a location.
+
+Plain filenames which contain a colon will be interpreted as URIs with an
+unknown protocol. To avoid this, prefix them with a path such as ``./``, or with
+the ``file:`` protocol.
+
+COMMANDS
+--------
+
+``help`` *COMMAND*
+
+  Displays a short synopsis of the available commands or provides detailed help
+  on a specific command.
+
+``version``
+
+  Prints the GLib version to which ``gio`` belongs.
+
+``cat`` *LOCATION*…
+
+  Concatenates the given files and prints them to the standard output.
+
+  The ``cat`` command works just like the traditional ``cat`` utility.
+
+  Mote: just pipe through ``cat`` if you need its formatting options like
+  ``-n``, ``-T`` or other.
+
+``copy`` [*OPTION*…] *SOURCE*… *DESTINATION*
+
+  Copies one or more files from ``SOURCE`` to ``DESTINATION``. If more than one
+  source is specified, the destination must be a directory.
+
+  The ``copy`` command is similar to the traditional ``cp`` utility.
+
+  **Options**
+
+  ``-T``, ``--no-target-directory``
+
+    Don’t copy into ``DESTINATION`` even if it is a directory.
+
+  ``-p``, ``--progress``
+
+    Show progress.
+
+  ``-i``, ``--interactive``
+
+    Prompt for confirmation before overwriting files.
+
+  ``--preserve``
+
+    Preserve all attributes of copied files.
+
+  ``-b``, ``--backup``
+
+    Create backups of existing destination files.
+
+  ``-P``, ``--no-dereference``
+
+    Never follow symbolic links.
+
+  ``--default-permissions``
+
+    Use the default permissions of the current process for the destination file,
+    rather than copying the permissions of the source file.
+
+``info`` [*OPTION*…] *LOCATION*…
+
+  Shows information about the given locations.
+
+  The ``info`` command is similar to the traditional ``ls`` utility.
+
+  **Options**
+
+  ``-w``, ``--query-writable``
+
+    List writable attributes.
+
+  ``-f``, ``--filesystem``
+
+    Show information about the filesystem that the given locations reside on.
+
+  ``-a``, ``--attributes=<ATTRIBUTES>``
+
+    The attributes to get.
+
+    Attributes can be specified with their GIO name, e.g. ``standard::icon``,
+    or just by namespace, e.g. ``unix``, or by ``*``, which matches all
+    attributes. Several attributes or groups of attributes can be specified,
+    separated by commas.
+
+    By default, all attributes are listed.
+
+  ``-n``, ``--nofollow-symlinks``
+
+    Don’t follow symbolic links.
+
+``launch`` *DESKTOP-FILE* [*FILE-ARG*…]
+
+  Launch a desktop file from any location given.
+
+  The ``launch`` command extends the behavior of the ``open`` command by
+  allowing any desktop file to be launched, not only those registered as file
+  handlers.
+
+``list`` [*OPTION*…] [*LOCATION*…]
+
+  Lists the contents of the given locations. If no location is given, the
+  contents of the current directory are shown.
+
+  The ``list`` command is similar to the traditional ``ls`` utility.
+
+  **Options**
+
+  ``-a``, ``--attributes=<ATTRIBUTES>``
+
+    The attributes to get.
+
+    Attributes can be specified with their GIO name, e.g. ``standard::icon``, or
+    just by namespace, e.g. ``unix``, or by ``*``, which matches all attributes.
+    Several attributes or groups of attributes can be specified, separated by
+    commas.
+
+    By default, all attributes are listed.
+
+  ``-h``, ``--hidden``
+
+    Show hidden files.
+
+  ``-l``, ``--long``
+
+    Use a long listing format.
+
+  ``-n``, ``--nofollow-symlinks``
+
+    Don’t follow symbolic links.
+
+  ``-d``, ``--print-display-names``
+
+    Print display names.
+
+  ``-u``, ``--print-uris``
+
+    Print full URIs.
+
+``mime`` *MIME-TYPE* [*HANDLER*]
+
+  If no handler is given, the ``mime`` command lists the registered and
+  recommended applications for the MIME type. If a handler is given, it is set
+  as the default handler for the MIME type.
+
+  Handlers must be specified by their desktop file name, including the
+  extension. Example: ``org.gnome.gedit.desktop``.
+
+``mkdir`` [*OPTION*…] *LOCATION*…
+
+  Creates directories.
+
+  The ``mkdir`` command is similar to the traditional ``mkdir`` utility.
+
+  **Options**
+
+  ``-p``, ``--parent``
+
+    Create parent directories when necessary.
+
+``monitor`` [*OPTION*…] [*LOCATION*…]
+
+  Monitors files or directories for changes, such as creation deletion, content
+  and attribute changes, and mount and unmount operations affecting the
+  monitored locations.
+
+  The ``monitor`` command uses the GIO file monitoring APIs to do its job. GIO
+  has different implementations for different platforms. The most common
+  implementation on Linux uses inotify.
+
+  **Options**
+
+  ``-d``, ``--dir=<LOCATION>``
+
+    Monitor the given location as a directory. Normally, the file type is used
+    to determine whether to monitor as a file or as a directory.
+
+  ``-f``, ``--file=<LOCATION>``
+
+    Monitor the given location as a file. Normally, the file type is used to
+    determine whether to monitor as a file or as a directory.
+
+  ``-D``, ``--direct=<LOCATION>``
+
+    Monitor the file directly. This allows changes made via hardlinks to be
+    captured.
+
+  ``-s``, ``--silent=<LOCATION>``
+
+    Monitor the file directly, but don’t report changes.
+
+  ``-n``, ``--no-moves``
+
+    Report moves and renames as simple deleted/created events.
+
+  ``-m``, ``--mounts``
+
+    Watch for mount events.
+
+``mount`` [*OPTION*…] [*LOCATION*…]
+
+  Provides commandline access to various aspects of GIO’s mounting
+  functionality.
+
+  Mounting refers to the traditional concept of arranging multiple file systems
+  and devices in a single tree, rooted at ``/``. Classical mounting happens in
+  the kernel and is controlled by the mount utility. GIO expands this concept by
+  introducing mount daemons that can make file systems available to GIO
+  applications without kernel involvement.
+
+  GIO mounts can require authentication, and the ``mount`` command may ask for
+  user IDs, passwords, and so on, when required.
+
+  **Options**
+
+  ``-m``, ``--mountable``
+
+    Mount as mountable.
+
+  ``-d``, ``--device=<ID>``
+
+    Mount volume with device file, or other identifier.
+
+  ``-u``, ``--unmount``
+
+    Unmount the location.
+
+  ``-e``, ``--eject``
+
+    Eject the location.
+
+  ``-t``, ``--stop=<DEVICE>``
+
+    Stop drive with device file.
+
+  ``-s``, ``--unmount-scheme=<SCHEME>``
+
+    Unmount all mounts with the given scheme.
+
+  ``-f``, ``--force``
+
+    Ignore outstanding file operations when unmounting or ejecting.
+
+  ``-a``, ``--anonymous``
+
+    Use an anonymous user when authenticating.
+
+  ``-l``, ``--list``
+
+    List all GIO mounts.
+
+  ``-o``, ``--monitor``
+
+    Monitor mount-related events.
+
+  ``-i``, ``--detail``
+
+    Show extra information.
+
+  ``--tcrypt-pim``
+
+    The numeric PIM when unlocking a VeraCrypt volume.
+
+  ``--tcrypt-hidden``
+
+    Mount a TCRYPT hidden volume.
+
+  ``--tcrypt-system``
+
+    Mount a TCRYPT system volume.
+
+``move`` [*OPTION*…] *SOURCE*… *DESTINATION*
+
+  Moves one or more files from ``SOURCE`` to ``DESTINATION``. If more than one
+  source is specified, the destination must be a directory.
+
+  The ``move`` command is similar to the traditional ``mv`` utility.
+
+  **Options**
+
+  ``-T``, ``--no-target-directory``
+
+    Don’t copy into ``DESTINATION`` even if it is a directory.
+
+  ``-p``, ``--progress``
+
+    Show progress.
+
+  ``-i``, ``--interactive``
+
+    Prompt for confirmation before overwriting files.
+
+  ``-b``, ``--backup``
+
+    Create backups of existing destination files.
+
+  ``-C``, ``--no-copy-fallback``
+
+    Don’t use copy and delete fallback.
+
+``open`` *LOCATION*…
+
+  Opens files with the default application that is registered to handle files of
+  this type.
+
+  GIO obtains this information from the shared-mime-info database, with per-user
+  overrides stored in ``$XDG_DATA_HOME/applications/mimeapps.list``.
+
+  The ``mime`` command can be used to change the default handler for a MIME
+  type.
+
+  Environment variables will not be set on the application, as it may be an
+  existing process which is activated to handle the new file.
+
+``rename`` *LOCATION* *NAME*
+
+  Renames a file.
+
+  The ``rename`` command is similar to the traditional ``rename`` utility.
+
+``remove`` [*OPTION*…] *LOCATION*…
+
+  Deletes each given file.
+
+  This command removes files irreversibly. If you want a reversible way to
+  remove files, see the ``trash`` command.
+
+  Note that not all URI schemes that are supported by GIO may allow deletion of
+  files.
+
+  The ``remove`` command is similar to the traditional ``rm`` utility.
+
+  **Options**
+
+  ``-f``, ``--force``
+
+    Ignore non-existent and non-deletable files.
+
+``save`` [*OPTION*…] *DESTINATION*
+
+  Reads from standard input and saves the data to the given location.
+
+  This is similar to just redirecting output to a file using traditional shell
+  syntax, but the ``save`` command allows saving to location that GIO can write
+  to.
+
+  **Options**
+
+  ``-b``, ``--backup``
+
+    Back up existing destination files.
+
+  ``-c``, ``--create``
+
+    Only create the destination if it doesn’t exist yet.
+
+  ``-a``, ``--append``
+
+    Append to the end of the file.
+
+  ``-p``, ``--private``
+
+    When creating, restrict access to the current user.
+
+  ``-u``, ``--unlink``
+
+    When replacing, replace as if the destination did not exist.
+
+  ``-v``, ``--print-etag``
+
+    Print the new ETag in the end.
+
+  ``-e``, ``--etag=<ETAG>``
+
+    The ETag of the file that is overwritten.
+
+``set`` [*OPTION*…] *LOCATION* *ATTRIBUTE* *VALUE*…
+
+  Sets a file attribute on a file.
+
+  File attributes can be specified with their GIO name, e.g ``standard::icon``.
+  Note that not all GIO file attributes are writable. Use the
+  ``--query-writable`` option of the ``info`` command to list writable file
+  attributes.
+
+  If the ``TYPE`` is unset, ``VALUE`` does not have to be specified. If the
+  ``TYPE`` is ``stringv``, multiple values can be given.
+
+  **Options**
+
+  ``-t``, ``--type=<TYPE>``
+
+    Specifies the type of the attribute. Supported types are ``string``,
+    ``stringv``, ``bytestring``, ``boolean``, ``uint32``, ``int32``, ``uint64``,
+    ``int64`` and ``unset``.
+
+    If the type is not specified, ``string`` is assumed.
+
+  ``-d``, ``--delete``
+
+    Unsets an attribute (same as setting its type to ``unset``).
+
+  ``-n``, ``--nofollow-symlinks``
+
+    Don’t follow symbolic links.
+
+``trash`` [*OPTION*…] [*LOCATION*…]
+
+  Sends files or directories to the ‘Trashcan’ or restore them from ‘Trashcan’.
+  This can be a different folder depending on where the file is located, and not
+  all file systems support this concept. In the common case that the file lives
+  inside a user’s home directory, the trash folder is ``$XDG_DATA_HOME/Trash``.
+
+  Note that moving files to the trash does not free up space on the file system
+  until the ‘Trashcan’ is emptied. If you are interested in deleting a file
+  irreversibly, see the ``remove`` command.
+
+  Inspecting and emptying the ‘Trashcan’ is normally supported by graphical file
+  managers such as Nautilus, but you can also see the trash with the command:
+  ``gio trash --list`` or ``gio list trash://``.
+
+  **Options**
+
+  ``-f``, ``--force``
+
+    Ignore non-existent and non-deletable files.
+
+  ``--empty``
+
+    Empty the trash.
+
+  ``--list``
+
+    List files in the trash with their original locations.
+
+  ``--restore``
+
+    Restore a file from trash to its original location. A URI beginning with
+    ``trash://`` is expected here. If the original directory doesn’t exist, it
+    will be recreated.
+
+``tree`` [*OPTION*…] [*LOCATION*…]
+
+  Lists the contents of the given locations recursively, in a tree-like format.
+  If no location is given, it defaults to the current directory.
+
+  The ``tree`` command is similar to the traditional ``tree`` utility.
+
+  **Options**
+
+  ``-h``, ``--hidden``
+
+    Show hidden files.
+
+  ``-l``, ``--follow-symlinks``
+
+    Follow symbolic links.
+
+EXIT STATUS
+-----------
+
+On success, ``0`` is returned, a non-zero failure code otherwise.
+
+SEE ALSO
+--------
+
+`cat(1) <man:cat(1)>`_, `cp(1) <man:cp(1)>`_, `ls(1) <man:ls(1)>`_,
+`mkdir(1) <man:mkdir(1)>`_, `mv(1) <man:mv(1)>`_, `rm(1) <man:rm(1)>`_,
+`tree(1) <man:tree(1)>`_

docs/reference/gio/gio.toml.in

@@ -0,0 +1,71 @@
+# SPDX-License-Identifier: LGPL-2.1-or-later
+# Copyright 2023 Matthias Clasen
+# Copyright 2023 Philip Withnall
+
+[library]
+name = "Gio"
+version = "@VERSION@"
+browse_url = "https://gitlab.gnome.org/GNOME/glib/"
+repository_url = "https://gitlab.gnome.org/GNOME/glib.git"
+website_url = "https://www.gtk.org"
+docs_urls = "https://docs.gtk.org/gio/"
+authors = "GLib Development Team"
+license = "LGPL-2.1-or-later"
+description = "Gio is a library providing useful classes for general purpose I/O, networking, IPC, settings, and other high level application functionality"
+dependencies = [ "GLib-2.0", "GModule-2.0", "GObject-2.0" ]
+devhelp = true
+search_index = true
+
+  [dependencies."GLib-2.0"]
+  name = "GLib"
+  description = "The base utility library"
+  docs_url = "https://docs.gtk.org/glib/"
+
+  [dependencies."GModule-2.0"]
+  name = "GModule"
+  description = "Portable API for dynamically loading modules"
+  docs_url = "https://docs.gtk.org/gmodule/"
+
+  [dependencies."GObject-2.0"]
+  name = "GObject"
+  description = "The base type system library"
+  docs_url = "https://docs.gtk.org/gobject/"
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[extra]
+urlmap_file = "../urlmap.js"
+# The same order will be used when generating the index
+content_files = [
+  "overview.md",
+  "file-attributes.md",
+  "tls-overview.md",
+
+  "error.md",
+
+  "pollable-utils.md",
+
+  "dbus-error.md",
+  "dbus-introspection.md",
+  "dbus-name-owning.md",
+  "dbus-name-watching.md",
+  "dbus-utils.md",
+  "menu-exporter.md",
+
+  "networking.md",
+
+  "migrating-gdbus.md",
+  "migrating-gconf.md",
+  "migrating-gnome-vfs.md",
+  "migrating-posix.md",
+
+  "io-scheduler.md",
+]
+content_images = [
+  "gvfs-overview.png",
+  "menu-example.png",
+  "menu-model.png",
+]

docs/reference/gio/gio.xml

@@ -1,809 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-<refentry id="gio">
-  <refentryinfo>
-    <title>gio</title>
-    <productname>GIO</productname>
-    <authorgroup>
-      <author>
-        <contrib>Developer</contrib>
-        <firstname>Matthias</firstname>
-        <surname>Clasen</surname>
-        <email>mclasen@redhat.com</email>
-      </author>
-    </authorgroup>
-  </refentryinfo>
-
-  <refmeta>
-    <refentrytitle>gio</refentrytitle>
-    <manvolnum>1</manvolnum>
-    <refmiscinfo class="manual">User Commands</refmiscinfo>
-  </refmeta>
-
-  <refnamediv>
-    <refname>gio</refname>
-    <refpurpose>GIO commandline tool</refpurpose>
-  </refnamediv>
-
-  <refsynopsisdiv>
-    <cmdsynopsis>
-      <command>gio</command>
-      <arg choice="plain">help</arg>
-      <arg choice="opt"><replaceable>COMMAND</replaceable></arg>
-    </cmdsynopsis>
-    <cmdsynopsis>
-      <command>gio</command>
-      <arg choice="plain">version</arg>
-    </cmdsynopsis>
-    <cmdsynopsis>
-      <command>gio</command>
-      <arg choice="plain">cat</arg>
-      <arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
-    </cmdsynopsis>
-    <cmdsynopsis>
-      <command>gio</command>
-      <arg choice="plain">copy</arg>
-      <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
-      <arg choice="plain" rep="repeat"><replaceable>SOURCE</replaceable></arg>
-      <arg choice="plain"><replaceable>DESTINATION</replaceable></arg>
-    </cmdsynopsis>
-    <cmdsynopsis>
-      <command>gio</command>
-      <arg choice="plain">info</arg>
-      <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
-      <arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
-    </cmdsynopsis>
-    <cmdsynopsis>
-      <command>gio</command>
-      <arg choice="plain">launch</arg>
-      <arg choice="plain"><replaceable>DESKTOP-FILE</replaceable></arg>
-      <arg choice="opt" rep="repeat"><replaceable>FILE-ARG</replaceable></arg>
-    </cmdsynopsis>
-    <cmdsynopsis>
-      <command>gio</command>
-      <arg choice="plain">list</arg>
-      <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
-      <arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
-    </cmdsynopsis>
-    <cmdsynopsis>
-      <command>gio</command>
-      <arg choice="plain">mime</arg>
-      <arg choice="plain"><replaceable>MIMETYPE</replaceable></arg>
-      <arg choice="opt"><replaceable>HANDLER</replaceable></arg>
-    </cmdsynopsis>
-    <cmdsynopsis>
-      <command>gio</command>
-      <arg choice="plain">mkdir</arg>
-      <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
-      <arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
-    </cmdsynopsis>
-    <cmdsynopsis>
-      <command>gio</command>
-      <arg choice="plain">monitor</arg>
-      <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
-      <arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
-    </cmdsynopsis>
-    <cmdsynopsis>
-      <command>gio</command>
-      <arg choice="plain">mount</arg>
-      <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
-      <arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
-    </cmdsynopsis>
-    <cmdsynopsis>
-      <command>gio</command>
-      <arg choice="plain">move</arg>
-      <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
-      <arg choice="plain" rep="repeat"><replaceable>SOURCE</replaceable></arg>
-      <arg choice="plain"><replaceable>DESTINATION</replaceable></arg>
-    </cmdsynopsis>
-    <cmdsynopsis>
-      <command>gio</command>
-      <arg choice="plain">open</arg>
-      <arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
-    </cmdsynopsis>
-    <cmdsynopsis>
-      <command>gio</command>
-      <arg choice="plain">rename</arg>
-      <arg choice="plain"><replaceable>LOCATION</replaceable></arg>
-      <arg choice="plain"><replaceable>NAME</replaceable></arg>
-    </cmdsynopsis>
-    <cmdsynopsis>
-      <command>gio</command>
-      <arg choice="plain">remove</arg>
-      <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
-      <arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
-    </cmdsynopsis>
-    <cmdsynopsis>
-      <command>gio</command>
-      <arg choice="plain">save</arg>
-      <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
-      <arg choice="plain"><replaceable>DESTINATION</replaceable></arg>
-    </cmdsynopsis>
-    <cmdsynopsis>
-      <command>gio</command>
-      <arg choice="plain">set</arg>
-      <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
-      <arg choice="plain"><replaceable>LOCATION</replaceable></arg>
-      <arg choice="plain"><replaceable>ATTRIBUTE</replaceable></arg>
-      <arg choice="plain" rep="repeat"><replaceable>VALUE</replaceable></arg>
-    </cmdsynopsis>
-    <cmdsynopsis>
-      <command>gio</command>
-      <arg choice="plain">trash</arg>
-      <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
-      <arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
-    </cmdsynopsis>
-    <cmdsynopsis>
-      <command>gio</command>
-      <arg choice="plain">tree</arg>
-      <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
-      <arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
-    </cmdsynopsis>
-  </refsynopsisdiv>
-
-  <refsect1>
-    <title>Description</title>
-    <para><command>gio</command> is a utility that makes many of the GIO
-      features available from the commandline. In doing so, it provides
-      commands that are similar to traditional utilities, but let you
-      use GIO locations instead of local files: for example you can use
-      something like <filename>smb://server/resource/file.txt</filename>
-      as a location.</para>
-    <para>Plain filenames which contain a colon will be interpreted as URIs
-      with an unknown protocol. To avoid this, prefix them with a path such as
-      <filename>./</filename>, or with the <literal>file:</literal> protocol.</para>
-  </refsect1>
-
-  <refsect1>
-    <title>Commands</title>
-
-    <variablelist>
-      <varlistentry>
-        <term>
-          <command>help</command>
-          <arg choice="opt"><replaceable>COMMAND</replaceable></arg>
-        </term>
-        <listitem>
-          <para>Displays a short synopsis of the available commands or provides
-            detailed help on a specific command.</para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
-          <command>version</command>
-        </term>
-        <listitem>
-          <para>Prints the GLib version to which <command>gio</command>
-            belongs.</para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
-          <command>cat</command>
-          <arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
-        </term>
-        <listitem>
-          <para>Concatenates the given files and prints them to the standard
-            output.</para>
-          <para>The <command>cat</command> command works just like the traditional <command>cat</command> utility.</para>
-          <para>Note: just pipe through <command>cat</command> if you need its formatting options
-            like <option>-n</option>, <option>-T</option> or other.</para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
-          <command>copy</command>
-          <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
-          <arg choice="plain" rep="repeat"><replaceable>SOURCE</replaceable></arg>
-          <arg choice="plain"><replaceable>DESTINATION</replaceable></arg>
-        </term>
-        <listitem>
-          <para>Copies one or more files from <replaceable>SOURCE</replaceable>
-            to <replaceable>DESTINATION</replaceable>. If more than one source
-            is specified, the destination must be a directory.</para>
-          <para>The <command>copy</command> command is similar to the traditional <command>cp</command> utility.</para>
-          <refsect3>
-            <title>Options</title>
-            <variablelist>
-              <varlistentry>
-                <term><option>-T</option>, <option>--no-target-directory</option></term>
-                <listitem><para>Don’t copy into <replaceable>DESTINATION</replaceable> even if it is a directory.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-p</option>, <option>--progress</option></term>
-                <listitem><para>Show progress.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-i</option>, <option>--interactive</option></term>
-                <listitem><para>Prompt for confirmation before overwriting files.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>--preserve</option></term>
-                <listitem><para>Preserve all attributes of copied files.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-b</option>, <option>--backup</option></term>
-                <listitem><para>Create backups of existing destination files.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-P</option>, <option>--no-dereference</option></term>
-                <listitem><para>Never follow symbolic links.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>--default-permissions</option></term>
-                <listitem><para>Use the default permissions of the current process for the destination file, rather than copying the permissions of the source file.</para></listitem>
-              </varlistentry>
-            </variablelist>
-          </refsect3>
-        </listitem>
-      </varlistentry>
-      <varlistentry>
-        <term>
-          <command>info</command>
-          <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
-          <arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
-        </term>
-        <listitem>
-          <para>Shows information about the given locations.</para>
-          <para>The <command>info</command> command is similar to the traditional <command>ls</command> utility.</para>
-          <refsect3>
-            <title>Options</title>
-            <variablelist>
-              <varlistentry>
-                <term><option>-w</option>, <option>--query-writable</option></term>
-                <listitem><para>List writable attributes.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-f</option>, <option>--filesystem</option></term>
-                <listitem><para>Show information about the filesystem that the given
-                locations reside on.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-a</option> <option>--attributes=<replaceable>ATTRIBUTES</replaceable></option></term>
-                <listitem><para>The attributes to get.</para>
-                  <para>Attributes can be specified with their GIO name, e.g.
-                    <literal>standard::icon</literal>, or just by namespace, e.g. <literal>unix</literal>, or by <literal>*</literal>,
-                    which matches all attributes. Several attributes or groups
-                    of attributes can be specified, separated by comma.</para>
-                  <para>By default, all attributes are listed.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-n</option>, <option>--nofollow-symlinks</option></term>
-                <listitem><para>Don’t follow symbolic links.</para></listitem>
-              </varlistentry>
-            </variablelist>
-          </refsect3>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
-          <command>launch</command>
-          <arg choice="plain"><replaceable>DESKTOP-FILE</replaceable></arg>
-          <arg choice="opt" rep="repeat"><replaceable>FILE-ARG</replaceable></arg>
-        </term>
-        <listitem>
-          <para>Launch a desktop file from any location given.</para>
-          <para>The <command>launch</command> command extends the behavior of the <command>open</command> command by allowing
-            any desktop file to be launched, not only those registered as file handlers.</para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
-          <command>list</command>
-          <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
-          <arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
-        </term>
-        <listitem>
-          <para>Lists the contents of the given locations. If no location is
-            given, the contents of the current directory are shown.</para>
-          <para>The <command>list</command> command is similar to the traditional <command>ls</command> utility.</para>
-          <refsect3>
-            <title>Options</title>
-            <variablelist>
-              <varlistentry>
-                <term><option>-a</option> <option>--attributes=<replaceable>ATTRIBUTES</replaceable></option></term>
-                <listitem><para>The attributes to get.</para>
-                  <para>Attributes can be specified with their GIO name, e.g.
-                    <literal>standard::icon</literal>, or just by namespace, e.g. <literal>unix</literal>, or by <literal>*</literal>,
-                    which matches all attributes. Several attributes or groups
-                    of attributes can be specified, separated by comma.</para>
-                  <para>By default, all attributes are listed.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-h</option>, <option>--hidden</option></term>
-                <listitem><para>Show hidden files.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-l</option>, <option>--long</option></term>
-                <listitem><para>Use a long listing format.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-n</option>, <option>--nofollow-symlinks</option></term>
-                <listitem><para>Don’t follow symbolic links.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-d</option>, <option>--print-display-names</option></term>
-                <listitem><para>Print display names.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-u</option>, <option>--print-uris</option></term>
-                <listitem><para>Print full URIs.</para></listitem>
-              </varlistentry>
-            </variablelist>
-          </refsect3>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
-          <command>mime</command>
-          <arg choice="plain"><replaceable>MIMETYPE</replaceable></arg>
-          <arg choice="opt"><replaceable>HANDLER</replaceable></arg>
-        </term>
-        <listitem>
-          <para>If no handler is given, the <command>mime</command> command lists the
-            registered and recommended applications for the mimetype.
-            If a handler is given, it is set as the default handler for
-            the mimetype.</para>
-          <para>Handlers must be specified by their desktop file name,
-            including the extension. Example: <literal>org.gnome.gedit.desktop</literal>.</para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
-          <command>mkdir</command>
-          <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
-          <arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
-        </term>
-        <listitem>
-          <para>Creates directories.</para>
-          <para>The <command>mkdir</command> command is similar to the traditional <command>mkdir</command> utility.</para>
-          <refsect3>
-            <title>Options</title>
-            <variablelist>
-              <varlistentry>
-                <term><option>-p</option>, <option>--parent</option></term>
-                <listitem><para>Create parent directories when necessary.</para></listitem>
-              </varlistentry>
-            </variablelist>
-          </refsect3>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
-          <command>monitor</command>
-          <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
-          <arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
-        </term>
-        <listitem>
-          <para>Monitors files or directories for changes, such as creation
-            deletion, content and attribute changes, and mount and unmount
-            operations affecting the monitored locations.</para>
-          <para>The <command>monitor</command> command uses the GIO file monitoring APIs to do
-            its job. GIO has different implementations for different platforms.
-            The most common implementation on Linux uses inotify.</para>
-          <refsect3>
-            <title>Options</title>
-            <variablelist>
-              <varlistentry>
-                <term><option>-d</option>, <option>--dir=<replaceable>LOCATION</replaceable></option></term>
-                <listitem><para>Monitor the given location as a directory. Normally,
-                  the file type is used to determine whether to monitor a file or directory.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-f</option>, <option>--file=<replaceable>LOCATION</replaceable></option></term>
-                <listitem><para>Monitor the given location as a file. Normally,
-                  the file type is used to determine whether to monitor a file or directory.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-D</option>, <option>--direct=<replaceable>LOCATION</replaceable></option></term>
-                <listitem><para>Monitor the file directly. This allows changes made via hardlinks to be captured.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-s</option>, <option>--silent=<replaceable>LOCATION</replaceable></option></term>
-                <listitem><para>Monitor the file directly, but don’t report changes.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-n</option>, <option>--no-moves</option></term>
-                <listitem><para>Report moves and renames as simple deleted/created events.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-m</option>, <option>--mounts</option></term>
-                <listitem><para>Watch for mount events.</para></listitem>
-              </varlistentry>
-            </variablelist>
-          </refsect3>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
-          <command>mount</command>
-          <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
-          <arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
-        </term>
-        <listitem>
-          <para>Provides commandline access to various aspects of GIO’s mounting
-            functionality.</para>
-          <para>Mounting refers to the traditional concept of arranging multiple
-            file systems and devices in a single tree, rooted at <filename>/</filename>. Classical
-            mounting happens in the kernel and is controlled by the mount utility.
-            GIO expands this concept by introducing mount daemons that can make
-            file systems available to GIO applications without kernel
-            involvement.</para>
-          <para>GIO mounts can require authentication, and the <command>mount</command> command
-            may ask for user IDs, passwords, and so on, when required.</para>
-          <refsect3>
-            <title>Options</title>
-            <variablelist>
-              <varlistentry>
-                <term><option>-m</option>, <option>--mountable</option></term>
-                <listitem><para>Mount as mountable.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-d</option>, <option>--device=<replaceable>ID</replaceable></option></term>
-                <listitem><para>Mount volume with device file, or other identifier.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-u</option>, <option>--unmount</option></term>
-                <listitem><para>Unmount the location.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-e</option>, <option>--eject</option></term>
-                <listitem><para>Eject the location.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-t</option>, <option>--stop=<replaceable>DEVICE</replaceable></option></term>
-                <listitem><para>Stop drive with device file.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-s</option>, <option>--unmount-scheme=<replaceable>SCHEME</replaceable></option></term>
-                <listitem><para>Unmount all mounts with the given scheme.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-f</option>, <option>--force</option></term>
-                <listitem><para>Ignore outstanding file operations when unmounting or ejecting.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-a</option>, <option>--anonymous</option></term>
-                <listitem><para>Use an anonymous user when authenticating.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-l</option>, <option>--list</option></term>
-                <listitem><para>List all GIO mounts.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-o</option>, <option>--monitor</option></term>
-                <listitem><para>Monitor mount-related events.</para>
-                </listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-i</option>, <option>--detail</option></term>
-                <listitem><para>Show extra information.</para>
-                </listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>--tcrypt-pim</option></term>
-                <listitem><para>The numeric PIM when unlocking a VeraCrypt volume.</para>
-                </listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>--tcrypt-hidden</option></term>
-                <listitem><para>Mount a TCRYPT hidden volume.</para>
-                </listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>--tcrypt-system</option></term>
-                <listitem><para>Mount a TCRYPT system volume.</para>
-                </listitem>
-              </varlistentry>
-            </variablelist>
-          </refsect3>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
-          <command>move</command>
-          <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
-          <arg choice="plain" rep="repeat"><replaceable>SOURCE</replaceable></arg>
-          <arg choice="plain"><replaceable>DESTINATION</replaceable></arg>
-        </term>
-        <listitem>
-          <para>Moves one or more files from <replaceable>SOURCE</replaceable>
-            to <replaceable>DESTINATION</replaceable>. If more than one source
-            is specified, the destination must be a directory.</para>
-          <para>The <command>move</command> command is similar to the traditional <command>mv</command> utility.</para>
-          <refsect3>
-            <title>Options</title>
-            <variablelist>
-              <varlistentry>
-                <term><option>-T</option>, <option>--no-target-directory</option></term>
-                <listitem><para>Don’t copy into <replaceable>DESTINATION</replaceable> even if it is a directory.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-p</option>, <option>--progress</option></term>
-                <listitem><para>Show progress.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-i</option>, <option>--interactive</option></term>
-                <listitem><para>Prompt for confirmation before overwriting files.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-b</option>, <option>--backup</option></term>
-                <listitem><para>Create backups of existing destination files.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-C</option>, <option>--no-copy-fallback</option></term>
-                <listitem><para>Don’t use copy and delete fallback.</para></listitem>
-              </varlistentry>
-            </variablelist>
-          </refsect3>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
-          <command>open</command>
-          <arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
-        </term>
-        <listitem>
-          <para>Opens files with the default application that is registered
-            to handle files of this type.</para>
-          <para>GIO obtains this information from the shared-mime-info
-            database, with per-user overrides stored in
-            <filename><envar>$XDG_DATA_HOME</envar>/applications/mimeapps.list</filename>.</para>
-          <para>The <command>mime</command> command can be used to change the default handler for
-            a mimetype.</para>
-          <para>Environment variables will not be set on the application, as it
-            may be an existing process which is activated to handle the new file.</para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
-          <command>rename</command>
-          <arg choice="plain"><replaceable>LOCATION</replaceable></arg>
-          <arg choice="plain"><replaceable>NAME</replaceable></arg>
-        </term>
-        <listitem>
-          <para>Renames a file.</para>
-          <para>The <command>rename</command> command is similar to the traditional <command>rename</command> utility.</para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
-          <command>remove</command>
-          <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
-          <arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
-        </term>
-        <listitem>
-          <para>Deletes each given file.</para>
-          <para>This command removes files irreversibly. If you want a reversible
-            way to remove files, see the <command>trash</command> command.</para>
-          <para>Note that not all URI schemes that are supported by GIO may
-            allow deletion of files.</para>
-          <para>The <command>remove</command> command is similar to the traditional <command>rm</command> utility.</para>
-          <refsect3>
-            <title>Options</title>
-            <variablelist>
-              <varlistentry>
-                <term><option>-f</option>, <option>--force</option></term>
-                <listitem><para>Ignore non-existent and non-deletable files.</para></listitem>
-              </varlistentry>
-            </variablelist>
-          </refsect3>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
-          <command>save</command>
-          <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
-          <arg choice="plain"><replaceable>DESTINATION</replaceable></arg>
-        </term>
-        <listitem>
-          <para>Reads from standard input and saves the data to the given
-            location.</para>
-          <para>This is similar to just redirecting output to a file using
-            traditional shell syntax, but the <command>save</command> command allows saving to
-            location that GIO can write to.</para>
-          <refsect3>
-            <title>Options</title>
-            <variablelist>
-              <varlistentry>
-                <term><option>-b</option>, <option>--backup</option></term>
-                <listitem><para>Back up existing destination files.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-c</option>, <option>--create</option></term>
-                <listitem><para>Only create the destination if it doesn’t exist yet.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-a</option>, <option>--append</option></term>
-                <listitem><para>Append to the end of the file.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-p</option>, <option>--private</option></term>
-                <listitem><para>When creating, restrict access to the current user.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-u</option>, <option>--unlink</option></term>
-                <listitem><para>When replacing, replace as if the destination did not exist.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-v</option>, <option>--print-etag</option></term>
-                <listitem><para>Print the new ETag in the end.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-e</option>, <option>--etag=<replaceable>ETAG</replaceable></option></term>
-                <listitem><para>The ETag of the file that is overwritten.</para></listitem>
-              </varlistentry>
-            </variablelist>
-          </refsect3>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
-          <command>set</command>
-          <arg choice="plain"><replaceable>LOCATION</replaceable></arg>
-          <arg choice="plain"><replaceable>ATTRIBUTE</replaceable></arg>
-          <arg choice="plain" rep="repeat"><replaceable>VALUE</replaceable></arg>
-        </term>
-        <listitem>
-          <para>Sets a file attribute on a file.</para>
-          <para>File attributes can be specified with their GIO name, e.g
-            <literal>standard::icon</literal>. Note that not all GIO file attributes are writable.
-            Use the <option>--query-writable</option> option of the <command>info</command> command to list
-            writable file attributes.</para>
-          <para>If the <replaceable>TYPE</replaceable> is unset,
-            <replaceable>VALUE</replaceable> does not have to be specified.
-            If the <replaceable>TYPE</replaceable> is <literal>stringv</literal>, multiple values can be given.</para>
-          <refsect3>
-            <title>Options</title>
-            <variablelist>
-              <varlistentry>
-                <term><option>-t</option>, <option>--type=<replaceable>TYPE</replaceable></option></term>
-                <listitem><para>Specifies the type of the attribute. Supported
-                  types are <literal>string</literal>, <literal>stringv</literal>,
-                  <literal>bytestring</literal>, <literal>boolean</literal>,
-                  <literal>uint32</literal>, <literal>int32</literal>,
-                  <literal>uint64</literal>, <literal>int64</literal> and <literal>unset</literal>.</para>
-                  <para>If the type is not specified, <literal>string</literal> is assumed.</para>
-                </listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-d</option>, <option>--delete</option></term>
-                <listitem><para>Unsets an attribute (same as setting it's type to <literal>unset</literal>).</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-n</option>, <option>--nofollow-symlinks</option></term>
-                <listitem><para>Don’t follow symbolic links.</para></listitem>
-              </varlistentry>
-            </variablelist>
-          </refsect3>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
-          <command>trash</command>
-          <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
-          <arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
-        </term>
-        <listitem>
-          <para>Sends files or directories to the ‘Trashcan’ or restore them from
-            ‘Trashcan’. This can be a different folder depending on where the file
-            is located, and not all file systems support this concept. In the common
-            case that the file lives inside a user’s home directory, the trash folder is
-            <filename><envar>$XDG_DATA_HOME</envar>/Trash</filename>.</para>
-          <para>Note that moving files to the trash does not free up space on
-            the file system until the ‘Trashcan’ is emptied. If you are interested
-            in deleting a file irreversibly, see the <command>remove</command> command.</para>
-          <para>Inspecting and emptying the ‘Trashcan’ is normally supported by
-            graphical file managers such as Nautilus, but you can also see the
-            trash with the command: <command>gio trash --list</command> or
-            <command>gio list trash://</command>.</para>
-          <refsect3>
-            <title>Options</title>
-            <variablelist>
-              <varlistentry>
-                <term><option>-f</option>, <option>--force</option></term>
-                <listitem><para>Ignore non-existent and non-deletable files.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>--empty</option></term>
-                <listitem><para>Empty the trash.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>--list</option></term>
-                <listitem><para>List files in the trash with their original locations</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>--restore</option></term>
-                <listitem><para>Restore a file from trash to its original location. A URI beginning
-                                with <literal>trash://</literal> is expected here. If the original
-                                directory doesn't exist, it will be recreated.</para></listitem>
-              </varlistentry>
-            </variablelist>
-          </refsect3>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
-          <command>tree</command>
-          <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
-          <arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
-        </term>
-        <listitem>
-          <para>Lists the contents of the given locations recursively, in a
-            tree-like format. If no location is given, it defaults to the current
-            directory.</para>
-          <para>The <command>tree</command> command is similar to the traditional <command>tree</command> utility.</para>
-          <refsect3>
-            <title>Options</title>
-            <variablelist>
-              <varlistentry>
-                <term><option>-h</option>, <option>--hidden</option></term>
-                <listitem><para>Show hidden files.</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><option>-l</option>, <option>--follow-symlinks</option></term>
-                <listitem><para>Follow symbolic links.</para></listitem>
-              </varlistentry>
-            </variablelist>
-          </refsect3>
-        </listitem>
-      </varlistentry>
-    </variablelist>
-  </refsect1>
-
-  <refsect1>
-    <title>Exit status</title>
-    <para>On success 0 is returned, a non-zero failure code otherwise.</para>
-  </refsect1>
-
-  <refsect1>
-    <title>See Also</title>
-    <para>
-      <citerefentry>
-        <refentrytitle>cat</refentrytitle>
-        <manvolnum>1</manvolnum>
-      </citerefentry>,
-      <citerefentry>
-        <refentrytitle>cp</refentrytitle>
-        <manvolnum>1</manvolnum>
-      </citerefentry>,
-      <citerefentry>
-        <refentrytitle>ls</refentrytitle>
-        <manvolnum>1</manvolnum>
-      </citerefentry>,
-      <citerefentry>
-        <refentrytitle>mkdir</refentrytitle>
-        <manvolnum>1</manvolnum>
-      </citerefentry>,
-      <citerefentry>
-        <refentrytitle>mv</refentrytitle>
-        <manvolnum>1</manvolnum>
-      </citerefentry>,
-      <citerefentry>
-        <refentrytitle>rm</refentrytitle>
-        <manvolnum>1</manvolnum>
-      </citerefentry>,
-      <citerefentry>
-        <refentrytitle>tree</refentrytitle>
-        <manvolnum>1</manvolnum>
-      </citerefentry>.
-    </para>
-  </refsect1>
-</refentry>

docs/reference/gio/glib-compile-resources.rst

@@ -0,0 +1,181 @@
+.. _glib-compile-resources(1):
+.. meta::
+   :copyright: Copyright 2012, 2016 Red Hat, Inc.
+   :copyright: Copyright 2012 Christian Persch
+   :copyright: Copyright 2016 Sam Thursfield
+   :copyright: Copyright 2016 Patrick Griffis
+   :copyright: Copyright 2018 Ninja-Koala
+   :copyright: Copyright 2018, 2021 Emmanuele Bassi
+   :copyright: Copyright 2020 Endless OS Foundation, LLC
+   :license: LGPL-2.1-or-later
+..
+   This has to be duplicated from above to make it machine-readable by `reuse`:
+   SPDX-FileCopyrightText: 2012, 2016 Red Hat, Inc.
+   SPDX-FileCopyrightText: 2012 Christian Persch
+   SPDX-FileCopyrightText: 2016 Sam Thursfield
+   SPDX-FileCopyrightText: 2016 Patrick Griffis
+   SPDX-FileCopyrightText: 2018 Ninja-Koala
+   SPDX-FileCopyrightText: 2018, 2021 Emmanuele Bassi
+   SPDX-FileCopyrightText: 2020 Endless OS Foundation, LLC
+   SPDX-License-Identifier: LGPL-2.1-or-later
+
+======================
+glib-compile-resources
+======================
+
+----------------------
+GLib resource compiler
+----------------------
+
+SYNOPSIS
+--------
+
+|  **glib-compile-resources** [*OPTION*…] *FILE*
+
+DESCRIPTION
+-----------
+
+``glib-compile-resources`` reads the resource description from ``FILE`` and the
+files that it references and creates a binary resource bundle that is suitable
+for use with the ``GResource`` API. The resulting bundle is then written out
+as-is, or as C source for linking into an application.
+
+The XML resource files normally have the filename extension ``.gresource.xml``.
+For a detailed description of the XML file format, see the
+``GResource`` `documentation <https://docs.gtk.org/gio/struct.Resource.html>`_.
+
+OPTIONS
+-------
+
+``-h``, ``--help``
+
+  Print help and exit.
+
+``--version``
+
+  Print program version and exit.
+
+``--target <TARGET>``
+
+  Store the compiled resources in the file ``TARGET``. If not specified a
+  filename based on the ``FILE`` basename is used.
+
+``--sourcedir <DIRECTORY>``
+
+  The files referenced in ``FILE`` are loaded from this directory. If not
+  specified, the current directory is used.
+
+``--generate``
+
+  Write the output file in the format selected for by its filename extension:
+
+  ``.c``
+
+    C source
+
+  ``.h``
+
+    C header
+
+  ``.gresource``
+
+    resource bundle
+
+``--generate-source``
+
+  Instead of a writing the resource bundle in binary form, create a C source
+  file that contains the resource bundle. This can then be compiled into an
+  application for easy access.
+
+``--generate-header``
+
+  Generate a header file for use with C code generated by ``--generate-source``.
+
+``--generate-dependencies``
+
+  Prints the list of files that the resource bundle references to standard
+  output. This can be used to track dependencies in the build system. For
+  example, the following make rule would mark ``test.gresource`` as depending on
+  all the files that ``test.gresource.xml`` includes, so that it is
+  automatically rebuilt if any of them change::
+
+     test.gresource: test.gresource.xml $(shell $(GLIB_COMPILE_RESOURCES) --generate-dependencies test.gresource.xml)
+
+  Note that this may or may not be portable to non-GNU ``make``.
+
+  Also see ``--dependency-file``.
+
+``--c-name``
+
+  Specify the prefix used for the C identifiers in the code generated by
+  ``--generate-source`` and ``--generate-header``.
+
+``--manual-register``
+
+  By default, code generated by ``--generate-source`` uses automatic
+  initialization of the resource. This works on most systems by using the
+  compiler support for constructors. However, some (uncommon) compilers may not
+  support this, you can then specify ``--manual-register``,
+  which will generate custom register and unregister functions that your code
+  can manually call at initialization and uninitialization time.
+
+``--internal``
+
+  By default, code generated by ``--generate-source`` declares all
+  initialization functions as ``extern``.  So they are exported unless this is
+  prevented by a link script or other means.  Since libraries usually want to
+  use the functions only internally it can be more useful to declare them as
+  ``G_GNUC_INTERNAL`` which is what ``--internal`` does.
+
+``--external-data``
+
+  By default, code generated by ``--generate-source`` embeds the resource data
+  as a string literal. When ``--external-data`` is given, the data is only
+  declared in the generated C file, and the data has to be linked externally.
+
+``--dependency-file <FILE>``
+
+  Write dependencies in the same style as ``gcc -M -MF`` to the given file. If
+  ``FILE`` is ``-``, the dependencies are written to the standard output. Unlike
+  ``--generate-dependencies``, this option can be combined with other
+  ``--generate`` options to generate dependencies as a side-effect of generating
+  sources.
+
+``--generate-phony-targets``
+
+  When creating a dependency file with ``--dependency-file`` include phony
+  targets in the same style as ``gcc -MP``. This would typically be used with
+  ``make``.
+
+``--compiler <NAME>``
+
+  Generate code that is going to target the given compiler ``NAME``. The current
+  two compiler modes are ``gcc``, for all GCC-compatible toolchains; and
+  ``msvc``, for the Microsoft Visual C Compiler. If this option isn’t set, then
+  the default will be taken from the ``CC`` environment variable.
+
+ENVIRONMENT
+-----------
+
+``XMLLINT``
+
+  The full path to the ``xmllint`` executable. This is used to preprocess
+  resources with the ``xml-stripblanks`` preprocessing option. If this
+  environment variable is not set, ``xmllint`` is searched for in the ``PATH``.
+
+``GDK_PIXBUF_PIXDATA``
+
+  Deprecated since gdk-pixbuf 2.32, as ``GResource`` supports embedding
+  modern image formats without conversion.
+
+  The full path to the ``gdk-pixbuf-pixdata`` executable. This is used to
+  preprocess resources with the ``to-pixdata`` preprocessing option. If this
+  environment variable is not set, ``gdk-pixbuf-pixdata`` is searched for in the
+  ``PATH``.
+
+``JSON_GLIB_FORMAT``
+
+  The full path to the ``json-glib-format`` executable. This is used to
+  preprocess resources with the ``json-stripblanks`` preprocessing option. If
+  this environment variable is not set, ``json-glib-format`` is searched for in
+  the ``PATH``.

docs/reference/gio/glib-compile-resources.xml

@@ -1,254 +0,0 @@
-<refentry id="glib-compile-resources" lang="en">
-
-<refentryinfo>
-  <title>glib-compile-schemas</title>
-  <productname>GIO</productname>
-  <authorgroup>
-    <author>
-      <contrib>Developer</contrib>
-      <firstname>Alexander</firstname>
-      <surname>Larsson</surname>
-    </author>
-  </authorgroup>
-</refentryinfo>
-
-<refmeta>
-  <refentrytitle>glib-compile-resources</refentrytitle>
-  <manvolnum>1</manvolnum>
-  <refmiscinfo class="manual">User Commands</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-  <refname>glib-compile-resources</refname>
-  <refpurpose>GLib resource compiler</refpurpose>
-</refnamediv>
-
-<refsynopsisdiv>
-  <cmdsynopsis>
-    <command>glib-compile-resources</command>
-    <arg choice="opt" rep="repeat">OPTION</arg>
-    <arg choice="req">FILE</arg>
-  </cmdsynopsis>
-</refsynopsisdiv>
-
-<refsect1><title>Description</title>
-<para><command>glib-compile-resources</command> reads the resource description from
-<replaceable>FILE</replaceable> and the files that it references
-and creates a binary resource bundle that is suitable for use with the
-<link linkend="GResource"><type>GResource</type></link> API.
-The resulting bundle is then written out as-is, or as C source for linking into
-an application.
-</para>
-<para>
-The XML resource files normally have the filename extension <filename>.gresource.xml</filename>.
-For a detailed description of the XML file format, see the
-<link linkend="GResource"><type>GResource</type></link> documentation.
-</para>
-</refsect1>
-
-<refsect1><title>Options</title>
-<variablelist>
-
-<varlistentry>
-<term><option>-h</option>, <option>--help</option></term>
-<listitem><para>
-Print help and exit
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--version</option></term>
-<listitem><para>
-Print program version and exit
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--target=<replaceable>TARGET</replaceable></option></term>
-<listitem><para>
-Store the compiled resources in the file <replaceable>TARGET</replaceable>.
-If not specified a filename based on the <replaceable>FILE</replaceable>
-basename is used.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--sourcedir=<replaceable>DIRECTORY</replaceable></option></term>
-<listitem><para>
-The files referenced in <replaceable>FILE</replaceable> are loaded from
-this directory. If not specified, the current directory is used.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--generate</option></term>
-<listitem><para>
-Write the output file in the format selected for by its filename extension:
-<variablelist>
-<varlistentry>
-<term><literal>.c</literal></term>
-<listitem><para>C source</para></listitem>
-</varlistentry>
-<varlistentry>
-<term><literal>.h</literal></term>
-<listitem><para>C header</para></listitem>
-</varlistentry>
-<varlistentry>
-<term><literal>.gresource</literal></term>
-<listitem><para>resource bundle</para></listitem>
-</varlistentry>
-</variablelist>
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--generate-source</option></term>
-<listitem><para>
-Instead of a writing the resource bundle in binary form create a C source file
-that contains the resource bundle. This can then be compiled into an
-application for easy access.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--generate-header</option></term>
-<listitem><para>
-Generate a header file for use with C code generated by
-<option>--generate-source</option>.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--generate-dependencies</option></term>
-<listitem><para>
-Prints the list of files that the resource bundle references to standard output.
-This can be used to track dependencies in the build system. For example, the
-following make rule would mark <replaceable>test.gresource</replaceable> as
-depending on all the files that <replaceable>test.gresource.xml</replaceable>
-includes, so that is is automatically rebuilt if any of them change:
-<programlisting>
-test.gresource: test.gresource.xml $(shell $(GLIB_COMPILE_RESOURCES) --generate-dependencies test.gresource.xml)
-</programlisting>
-Note that this may or may not be portable to non-GNU <command>make</command>.
-</para>
-<para>
-Also see <option>--dependency-file</option>.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--c-name</option></term>
-<listitem><para>
-Specify the prefix used for the C identifiers in the code generated by
-<option>--generate-source</option> and <option>--generate-header</option>.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--manual-register</option></term>
-<listitem><para>
-By default code generated by <option>--generate-source</option> uses automatic
-initialization of the resource. This works on most systems by using the
-compiler support for constructors. However, some (uncommon) compilers may not
-support this, you can then specify <option>--manual-register</option>,
-which will generate custom register and unregister functions that your code
-can manually call at initialization and uninitialization time.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--internal</option></term>
-<listitem><para>
-By default code generated by <option>--generate-source</option> declares all
-initialization functions as <type>extern</type>.  So they are exported
-unless this is prevented by a link script or other means.  Since libraries
-usually want to use the functions only internally it can be more useful to
-declare them as
-<link linkend="G-GNUC-INTERNAL:CAPS"><literal>G_GNUC_INTERNAL</literal></link>
-which is what <option>--internal</option> does.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--external-data</option></term>
-<listitem><para>
-By default code generated by <option>--generate-source</option> embeds the
-resource data as a string literal. When <option>--external-data</option>
-is given, the data is only declared in the generated C file, and the data
-has to be linked externally.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--dependency-file=<replaceable>FILE</replaceable></option></term>
-<listitem><para>
-Write dependencies in the same style as gcc -M -MF to the given file.
-If <option>FILE</option> is -, the dependencies are written to the standard
-output. Unlike <option>--generate-dependencies</option>, this option can be
-combined with other <option>--generate</option> options to generate dependencies
-as a side-effect of generating sources.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--generate-phony-targets</option></term>
-<listitem><para>
-When creating a dependency file with <option>--dependency-file</option>
-include phony targets in the same style as gcc -MP. This would typically
-be used with <literal>make</literal>.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--compiler=<replaceable>NAME</replaceable></option></term>
-<listitem><para>
-Generate code that is going to target the given compiler <replaceable>NAME</replaceable>.
-The current two compiler modes are "gcc", for all GCC-compatible toolchains; and "msvc",
-for the Microsoft Visual C Compiler. If this option isn't set, then the default will be
-taken from the <envar>CC</envar> environment variable.
-</para></listitem>
-</varlistentry>
-
-</variablelist>
-</refsect1>
-
-<refsect1><title>Environment</title>
-<variablelist>
-
-<varlistentry>
-<term><envar>XMLLINT</envar></term>
-<listitem><para>
-The full path to the <command>xmllint</command> executable. This is used to
-preprocess resources with the <literal>xml-stripblanks</literal> preprocessing
-option. If this environment variable is not set, <command>xmllint</command> is
-searched for in the <envar>PATH</envar>.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><envar>GDK_PIXBUF_PIXDATA</envar></term>
-<listitem><para>
-Deprecated since gdk-pixbuf 2.32, as <type>GResource</type> supports embedding
-modern image formats without conversion.
-</para><para>
-The full path to the <command>gdk-pixbuf-pixdata</command> executable. This is
-used to preprocess resources with the <literal>to-pixdata</literal> preprocessing
-option. If this environment variable is not set, <command>gdk-pixbuf-pixdata</command>
-is searched for in the <envar>PATH</envar>.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><envar>JSON_GLIB_FORMAT</envar></term>
-<listitem><para>
-The full path to the <command>json-glib-format</command> executable. This is used
-to preprocess resources with the <literal>json-stripblanks</literal> preprocessing
-option. If this environment variable is not set, <command>json-glib-format</command>
-is searched for in the <envar>PATH</envar>.
-</para></listitem>
-</varlistentry>
-
-</variablelist>
-</refsect1>
-</refentry>

docs/reference/gio/glib-compile-schemas.rst

@@ -0,0 +1,83 @@
+.. _glib-compile-schemas(1):
+.. meta::
+   :copyright: Copyright 2010, 2011, 2012, 2015 Red Hat, Inc.
+   :copyright: Copyright 2012 Allison Karlitskaya
+   :copyright: Copyright 2016 Sam Thursfield
+   :license: LGPL-2.1-or-later
+..
+   This has to be duplicated from above to make it machine-readable by `reuse`:
+   SPDX-FileCopyrightText: 2010, 2011, 2012, 2015 Red Hat, Inc.
+   SPDX-FileCopyrightText: 2012 Allison Karlitskaya
+   SPDX-FileCopyrightText: 2016 Sam Thursfield
+   SPDX-License-Identifier: LGPL-2.1-or-later
+
+====================
+glib-compile-schemas
+====================
+
+-------------------------
+GSettings schema compiler
+-------------------------
+
+SYNOPSIS
+--------
+
+|  **glib-compile-schemas** [*OPTION*…] *DIRECTORY*
+
+DESCRIPTION
+-----------
+
+``glib-compile-schemas`` compiles all the GSettings XML schema files in
+``DIRECTORY`` into a binary file with the name ``gschemas.compiled`` that can be
+used by ``GSettings``. The XML schema files must have the filename extension
+``.gschema.xml``. For a detailed description of the XML file format, see the
+``GSettings`` documentation.
+
+At runtime, GSettings looks for schemas in the ``glib-2.0/schemas``
+subdirectories of all directories specified in the ``XDG_DATA_DIRS`` environment
+variable. The usual location to install schema files is
+``/usr/share/glib-2.0/schemas``.
+
+In addition to schema files, ``glib-compile-schemas`` reads ‘vendor override’
+files, which are key files that can override default values for keys in
+the schemas. The group names in the key files are the schema ID, and the
+values are written in serialized GVariant form.
+Vendor override files must have the filename extension
+``.gschema.override``.
+
+By convention, vendor override files begin with ``nn_`` where ``nn`` is a number
+from 00 to 99.  Higher numbered files have higher priority (e.g. if the same
+override is made in a file numbered 10 and then again in a file numbered 20, the
+override from 20 will take precedence).
+
+OPTIONS
+-------
+
+``-h``, ``--help``
+
+  Print help and exit.
+
+``--version``
+
+  Print program version and exit.
+
+``--targetdir <TARGET>``
+
+  Store ``gschemas.compiled`` in the ``TARGET`` directory instead of
+  ``DIRECTORY``.
+
+``--strict``
+
+  Abort on any errors in schemas. Without this option, faulty schema files are
+  simply omitted from the resulting compiled schema.
+
+``--dry-run``
+
+  Don’t write ``gschemas.compiled``. This option can be used to check
+  ``.gschema.xml`` sources for errors.
+
+``--allow-any-name``
+
+  Do not enforce restrictions on key names. Note that this option is purely
+  to facility the transition from GConf, and will be removed at some time
+  in the future.

docs/reference/gio/glib-compile-schemas.xml

@@ -1,118 +0,0 @@
-<refentry id="glib-compile-schemas" lang="en">
-
-<refentryinfo>
-  <title>glib-compile-schemas</title>
-  <productname>GIO</productname>
-  <authorgroup>
-    <author>
-      <contrib>Developer</contrib>
-      <firstname>Ryan</firstname>
-      <surname>Lortie</surname>
-    </author>
-  </authorgroup>
-</refentryinfo>
-
-<refmeta>
-  <refentrytitle>glib-compile-schemas</refentrytitle>
-  <manvolnum>1</manvolnum>
-  <refmiscinfo class="manual">User Commands</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-  <refname>glib-compile-schemas</refname>
-  <refpurpose>GSettings schema compiler</refpurpose>
-</refnamediv>
-
-<refsynopsisdiv>
-  <cmdsynopsis>
-    <command>glib-compile-schemas</command>
-    <arg choice="opt" rep="repeat">OPTION</arg>
-    <arg choice="req">DIRECTORY</arg>
-  </cmdsynopsis>
-</refsynopsisdiv>
-
-<refsect1><title>Description</title>
-<para><command>glib-compile-schemas</command> compiles all the GSettings XML
-schema files in <replaceable>DIRECTORY</replaceable> into a binary file
-with the name <filename>gschemas.compiled</filename> that can be used
-by <link linkend="GSettings"><type>GSettings</type></link>. The XML schema
-files must have the filename extension <filename>.gschema.xml</filename>.
-For a detailed description of the XML file format, see the
-<link linkend="GSettings"><type>GSettings</type></link> documentation.
-</para>
-<para>
-At runtime, GSettings looks for schemas in the
-<filename>glib-2.0/schemas</filename> subdirectories of all directories
-specified in the <envar>XDG_DATA_DIRS</envar> environment variable. The
-usual location to install schema files is
-<filename>/usr/share/glib-2.0/schemas</filename>.
-</para>
-<para>
-In addition to schema files, glib-compile-schemas reads 'vendor override'
-files, which are key files that can override default values for keys in
-the schemas. The group names in the key files are the schema id, and the
-values are written in serialized GVariant form.
-Vendor override files must have the filename extension
-<filename>.gschema.override</filename>.
-</para>
-<para>
-By convention, vendor override files begin with <filename>nn_</filename>
-where <filename>nn</filename> is a number from 00 to 99.  Higher
-numbered files have higher priority (eg: if the same override is made in
-a file numbered 10 and then again in a file numbered 20, the override
-from 20 will take precedence).
-</para>
-</refsect1>
-
-<refsect1><title>Options</title>
-<variablelist>
-
-<varlistentry>
-<term><option>-h</option>, <option>--help</option></term>
-<listitem><para>
-Print help and exit
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--version</option></term>
-<listitem><para>
-Print program version and exit
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--targetdir=<replaceable>TARGET</replaceable></option></term>
-<listitem><para>
-Store <filename>gschemas.compiled</filename> in the <replaceable>TARGET</replaceable> directory instead of <replaceable>DIRECTORY</replaceable>.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--strict</option></term>
-<listitem><para>
-Abort on any errors in schemas. Without this option, faulty schema files are
-simply omitted from the resulting compiled schema.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--dry-run</option></term>
-<listitem><para>
-Don't write <filename>gschemas.compiled</filename>. This option can be used
-to check <filename>.gschema.xml</filename> sources for errors.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--allow-any-name</option></term>
-<listitem><para>
-Do not enforce restrictions on key names. Note that this option is purely
-to facility the transition from GConf, and will be removed at some time
-in the future.
-</para></listitem>
-</varlistentry>
-
-</variablelist>
-</refsect1>
-</refentry>

docs/reference/gio/gresource.rst

@@ -0,0 +1,66 @@
+.. _gresource(1):
+.. meta::
+   :copyright: Copyright 2012 Red Hat, Inc.
+   :license: LGPL-2.1-or-later
+..
+   This has to be duplicated from above to make it machine-readable by `reuse`:
+   SPDX-FileCopyrightText: 2012 Red Hat, Inc.
+   SPDX-License-Identifier: LGPL-2.1-or-later
+
+=========
+gresource
+=========
+
+--------------
+GResource tool
+--------------
+
+SYNOPSIS
+--------
+
+|  **gresource** [--section *SECTION*] list *FILE* [*PATH*]
+|  **gresource** [--section *SECTION*] details *FILE* [*PATH*]
+|  **gresource** [--section *SECTION*] extract *FILE* *PATH*
+|  **gresource** sections *FILE*
+|  **gresource** help [*COMMAND*]
+
+DESCRIPTION
+-----------
+
+``gresource`` offers a simple commandline interface to ``GResource``. It lets
+you list and extract resources that have been compiled into a resource file or
+included in an ELF file (a binary or a shared library).
+
+The file to operate on is specified by the ``FILE`` argument.
+
+If an ELF file includes multiple sections with resources, it is possible to
+select which one to operate on with the ``--section`` option. Use the
+``sections`` command to find available sections.
+
+COMMANDS
+--------
+
+``list``
+
+  Lists resources. If ``SECTION`` is given, only list resources in this section.
+  If ``PATH`` is given, only list matching resources.
+
+``details``
+
+  Lists resources with details. If ``SECTION`` is given, only list resources in
+  this section. If ``PATH`` is given, only list matching resources. Details
+  include the section, size and compression of each resource.
+
+``extract``
+
+  Extracts the resource named by ``PATH`` to stdout. Note that resources may
+  contain binary data.
+
+``sections``
+
+  Lists sections containing resources. This is only interesting if ``FILE`` is
+  an ELF file.
+
+``help``
+
+  Prints help and exits.

docs/reference/gio/gresource.xml

@@ -1,127 +0,0 @@
-<refentry id="gresource-tool" lang="en">
-
-<refentryinfo>
-  <title>gresource</title>
-  <productname>GIO</productname>
-  <authorgroup>
-    <author>
-      <contrib>Developer</contrib>
-      <firstname>Matthias</firstname>
-      <surname>Clasen</surname>
-    </author>
-  </authorgroup>
-</refentryinfo>
-
-<refmeta>
-  <refentrytitle>gresource</refentrytitle>
-  <manvolnum>1</manvolnum>
-  <refmiscinfo class="manual">User Commands</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-  <refname>gresource</refname>
-  <refpurpose>GResource tool</refpurpose>
-</refnamediv>
-
-<refsynopsisdiv>
-  <cmdsynopsis>
-    <command>gresource</command>
-    <arg choice="opt">--section <replaceable>SECTION</replaceable></arg>
-    <arg choice="plain">list</arg>
-    <arg choice="plain"><replaceable>FILE</replaceable></arg>
-    <arg choice="opt"><replaceable>PATH</replaceable></arg>
-  </cmdsynopsis>
-  <cmdsynopsis>
-    <command>gresource</command>
-    <arg choice="opt">--section <replaceable>SECTION</replaceable></arg>
-    <arg choice="plain">details</arg>
-    <arg choice="plain"><replaceable>FILE</replaceable></arg>
-    <arg choice="opt"><replaceable>PATH</replaceable></arg>
-  </cmdsynopsis>
-  <cmdsynopsis>
-    <command>gresource</command>
-    <arg choice="opt">--section <replaceable>SECTION</replaceable></arg>
-    <arg choice="plain">extract</arg>
-    <arg choice="plain"><replaceable>FILE</replaceable></arg>
-    <arg choice="plain"><replaceable>PATH</replaceable></arg>
-  </cmdsynopsis>
-  <cmdsynopsis>
-    <command>gresource</command>
-    <arg choice="plain">sections</arg>
-    <arg choice="plain"><replaceable>FILE</replaceable></arg>
-  </cmdsynopsis>
-  <cmdsynopsis>
-    <command>gresource</command>
-    <arg choice="plain">help</arg>
-    <arg choice="opt"><replaceable>COMMAND</replaceable></arg>
-  </cmdsynopsis>
-</refsynopsisdiv>
-
-<refsect1><title>Description</title>
-<para><command>gresource</command> offers a simple commandline
-interface to <link linkend="GResource"><type>GResource</type></link>.
-It lets you list and extract resources that have been compiled
-into a resource file or included in an elf file (a binary or a
-shared library).
-</para>
-<para>
-The file to operate on is specified by the <replaceable>FILE</replaceable>
-argument.
-</para>
-<para>
-If an elf file includes multiple sections with resources, it is
-possible to select which one to operate on with the
-<arg choice="plain">--section</arg> option. Use the
-<arg choice="plain">sections</arg> command to find available sections.
-</para>
-</refsect1>
-
-<refsect1><title>Commands</title>
-<variablelist>
-
-<varlistentry>
-<term><option>list</option></term>
-<listitem><para>
-Lists resources. If <replaceable>SECTION</replaceable> is given, only
-list resources in this section. If <replaceable>PATH</replaceable> is
-given, only list matching resources.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>details</option></term>
-<listitem><para>
-Lists resources with details. If <replaceable>SECTION</replaceable>
-is given, only list resources in this section. If
-<replaceable>PATH</replaceable> is given, only list matching resources.
-Details include the section, size and compression of each resource.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>extract</option></term>
-<listitem><para>
-Extracts the resource named by <replaceable>PATH</replaceable> to stdout.
-Note that resources may contain binary data.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>sections</option></term>
-<listitem><para>
-Lists sections containing resources. This is only interesting if
-<replaceable>FILE</replaceable> is an elf file.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>help</option></term>
-<listitem><para>
-Prints help and exits.
-</para></listitem>
-</varlistentry>
-
-</variablelist>
-
-</refsect1>
-</refentry>

docs/reference/gio/gsettings.rst

@@ -0,0 +1,125 @@
+.. _gsettings(1):
+.. meta::
+   :copyright: Copyright 2010, 2011, 2013 Red Hat, Inc.
+   :copyright: Copyright 2011 Colin Walters
+   :copyright: Copyright 2016 Jeremy Whiting
+   :copyright: Copyright 2018 Arnaud Bonatti
+   :license: LGPL-2.1-or-later
+..
+   This has to be duplicated from above to make it machine-readable by `reuse`:
+   SPDX-FileCopyrightText: 2010, 2011, 2013 Red Hat, Inc.
+   SPDX-FileCopyrightText: 2011 Colin Walters
+   SPDX-FileCopyrightText: 2016 Jeremy Whiting
+   SPDX-FileCopyrightText: 2018 Arnaud Bonatti
+   SPDX-License-Identifier: LGPL-2.1-or-later
+
+=========
+gsettings
+=========
+
+----------------------------
+GSettings configuration tool
+----------------------------
+
+SYNOPSIS
+--------
+
+|  **gsettings** get *SCHEMA*[:*PATH*] *KEY*
+|  **gsettings** monitor *SCHEMA*[:*PATH*] *KEY*
+|  **gsettings** writable *SCHEMA*[:*PATH*] *KEY*
+|  **gsettings** range *SCHEMA*[:*PATH*] *KEY*
+|  **gsettings** describe *SCHEMA*[:*PATH*] *KEY*
+|  **gsettings** set *SCHEMA*[:*PATH*] *KEY* *VALUE*
+|  **gsettings** reset *SCHEMA*[:*PATH*] *KEY*
+|  **gsettings** reset-recursively *SCHEMA*[:*PATH*]
+|  **gsettings** list-schemas [--print-paths]
+|  **gsettings** list-relocatable-schemas
+|  **gsettings** list-keys *SCHEMA*[:*PATH*]
+|  **gsettings** list-children *SCHEMA*[:*PATH*]
+|  **gsettings** list-recursively [*SCHEMA*[:*PATH*]]
+|  **gsettings** help [*COMMAND*]
+
+DESCRIPTION
+-----------
+
+``gsettings`` offers a simple commandline interface to ``GSettings``. It lets
+you get, set or monitor an individual key for changes.
+
+The ``SCHEMA`` and ``KEY`` arguments are required for most commands to specify
+the schema ID and the name of the key to operate on. The schema ID may
+optionally have a ``:PATH`` suffix. Specifying the path is only needed if the
+schema does not have a fixed path.
+
+When setting a key, you also need specify a ``VALUE``. The format for the value
+is that of a serialized ``GVariant``, so e.g. a string must include explicit
+quotes: ``'foo'``. This format is also used when printing out values.
+
+Note that ``gsettings`` needs a D-Bus session bus connection to write changes to
+the dconf database.
+
+COMMANDS
+--------
+
+``get``
+
+  Gets the value of ``KEY``. The value is printed out as a serialized
+  ``GVariant``.
+
+``monitor``
+
+  Monitors ``KEY`` for changes and prints the changed values. If no ``KEY`` is
+  specified, all keys in the schema are monitored. Monitoring will continue
+  until the process is terminated.
+
+``writable``
+
+  Finds out whether ``KEY`` is writable.
+
+``range``
+
+  Queries the range of valid values for ``KEY``.
+
+``describe``
+
+  Queries the description of valid values for ``KEY``.
+
+``set``
+
+  Sets the value of ``KEY`` to ``VALUE``. The value is specified as a serialized
+  ``GVariant``.
+
+``reset``
+
+  Resets ``KEY`` to its default value.
+
+``reset-recursively``
+
+  Reset all keys under the given ``SCHEMA``.
+
+``list-schemas``
+
+  Lists the installed, non-relocatable schemas. See ``list-relocatable-schemas``
+  if you are interested in relocatable schemas. If ``--print-paths`` is given,
+  the path where each schema is mapped is also printed.
+
+``list-relocatable-schemas``
+
+  Lists the installed, relocatable schemas. See ``list-schemas`` if you are
+  interested in non-relocatable schemas.
+
+``list-keys``
+
+  Lists the keys in ``SCHEMA``.
+
+``list-children``
+
+  Lists the children of ``SCHEMA``.
+
+``list-recursively``
+
+  Lists keys and values, recursively. If no ``SCHEMA`` is given, list keys in
+  all schemas.
+
+``help``
+
+  Prints help and exits.

docs/reference/gio/gsettings.xml

@@ -1,248 +0,0 @@
-<refentry id="gsettings-tool" lang="en">
-
-<refentryinfo>
-  <title>gsettings</title>
-  <productname>GIO</productname>
-  <authorgroup>
-    <author>
-      <contrib>Developer</contrib>
-      <firstname>Ryan</firstname>
-      <surname>Lortie</surname>
-    </author>
-  </authorgroup>
-</refentryinfo>
-
-<refmeta>
-  <refentrytitle>gsettings</refentrytitle>
-  <manvolnum>1</manvolnum>
-  <refmiscinfo class="manual">User Commands</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-  <refname>gsettings</refname>
-  <refpurpose>GSettings configuration tool</refpurpose>
-</refnamediv>
-
-<refsynopsisdiv>
-  <cmdsynopsis>
-    <command>gsettings</command>
-    <arg choice="plain">get</arg>
-    <arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
-    <arg choice="plain"><replaceable>KEY</replaceable></arg>
-  </cmdsynopsis>
-  <cmdsynopsis>
-    <command>gsettings</command>
-    <arg choice="plain">monitor</arg>
-    <arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
-    <arg choice="opt"><replaceable>KEY</replaceable></arg>
-  </cmdsynopsis>
-  <cmdsynopsis>
-    <command>gsettings</command>
-    <arg choice="plain">writable</arg>
-    <arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
-    <arg choice="plain"><replaceable>KEY</replaceable></arg>
-  </cmdsynopsis>
-  <cmdsynopsis>
-    <command>gsettings</command>
-    <arg choice="plain">range</arg>
-    <arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
-    <arg choice="plain"><replaceable>KEY</replaceable></arg>
-  </cmdsynopsis>
-  <cmdsynopsis>
-    <command>gsettings</command>
-    <arg choice="plain">describe</arg>
-    <arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
-    <arg choice="plain"><replaceable>KEY</replaceable></arg>
-  </cmdsynopsis>
-  <cmdsynopsis>
-    <command>gsettings</command>
-    <arg choice="plain">set</arg>
-    <arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
-    <arg choice="plain"><replaceable>KEY</replaceable></arg>
-    <arg choice="plain"><replaceable>VALUE</replaceable></arg>
-  </cmdsynopsis>
-  <cmdsynopsis>
-    <command>gsettings</command>
-    <arg choice="plain">reset</arg>
-    <arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
-    <arg choice="plain"><replaceable>KEY</replaceable></arg>
-  </cmdsynopsis>
-  <cmdsynopsis>
-    <command>gsettings</command>
-    <arg choice="plain">reset-recursively</arg>
-    <arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
-  </cmdsynopsis>
-  <cmdsynopsis>
-    <command>gsettings</command>
-    <arg choice="plain">list-schemas</arg>
-    <arg choice="opt">--print-paths</arg>
-  </cmdsynopsis>
-  <cmdsynopsis>
-    <command>gsettings</command>
-    <arg choice="plain">list-relocatable-schemas</arg>
-  </cmdsynopsis>
-  <cmdsynopsis>
-    <command>gsettings</command>
-    <arg choice="plain">list-keys</arg>
-    <arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
-  </cmdsynopsis>
-  <cmdsynopsis>
-    <command>gsettings</command>
-    <arg choice="plain">list-children</arg>
-    <arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
-  </cmdsynopsis>
-  <cmdsynopsis>
-    <command>gsettings</command>
-    <arg choice="plain">list-recursively</arg>
-    <arg choice="opt"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
-  </cmdsynopsis>
-  <cmdsynopsis>
-    <command>gsettings</command>
-    <arg choice="plain">help</arg>
-    <arg choice="opt"><replaceable>COMMAND</replaceable></arg>
-  </cmdsynopsis>
-</refsynopsisdiv>
-
-<refsect1><title>Description</title>
-<para><command>gsettings</command> offers a simple commandline
-interface to <link linkend="GSettings"><type>GSettings</type></link>.
-It lets you get, set or monitor an individual key for changes.
-</para>
-<para>
-The <replaceable>SCHEMA</replaceable> and <replaceable>KEY</replaceable>
-arguments are required for most commands to specify the schema id and the
-name of the key to operate on. The schema id may optionally have a
-:<replaceable>PATH</replaceable> suffix. Specifying the path is only needed
-if the schema does not have a fixed path.
-</para>
-<para>
-When setting a key, you also need specify a <replaceable>VALUE</replaceable>
-The format for the value is that of a serialized
-<link linkend="GVariant"><type>GVariant</type></link>,
-so e.g. a string
-must include explicit quotes: "'foo'". This format is also used when printing
-out values.
-</para>
-<para>
-Note that gsettings needs a D-Bus session bus connection to write changes to
-the dconf database.
-</para>
-</refsect1>
-
-<refsect1><title>Commands</title>
-<variablelist>
-
-<varlistentry>
-<term><option>get</option></term>
-<listitem><para>
-Gets the value of <replaceable>KEY</replaceable>.
-The value is printed out as a serialized
-<link linkend="GVariant"><type>GVariant</type></link>.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>monitor</option></term>
-<listitem><para>
-Monitors <replaceable>KEY</replaceable> for changes and prints the changed
-values. If no <replaceable>KEY</replaceable> is specified, all keys in the
-schema are monitored. Monitoring will continue until the process is terminated.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>writable</option></term>
-<listitem><para>
-Finds out whether <replaceable>KEY</replaceable> is writable.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>range</option></term>
-<listitem><para>
-Queries the range of valid values for <replaceable>KEY</replaceable>.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>describe</option></term>
-<listitem><para>
-Queries the description of valid values for <replaceable>KEY</replaceable>.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>set</option></term>
-<listitem><para>
-Sets the value of <replaceable>KEY</replaceable> to
-<replaceable>VALUE</replaceable>. The value is specified as a serialized
-<link linkend="GVariant"><type>GVariant</type></link>.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>reset</option></term>
-<listitem><para>
-Resets <replaceable>KEY</replaceable> to its default value.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>reset-recursively</option></term>
-<listitem><para>
-Reset all keys under the given <replaceable>SCHEMA</replaceable>.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>list-schemas</option></term>
-<listitem><para>
-Lists the installed, non-relocatable schemas.
-See <option>list-relocatable-schemas</option> if you are interested in
-relocatable schemas. If <optional><option>--print-paths</option></optional>
-is given, the path where each schema is mapped is also printed.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>list-relocatable-schemas</option></term>
-<listitem><para>
-Lists the installed, relocatable schemas.
-See <option>list-schemas</option> if you are interested in
-non-relocatable schemas.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>list-keys</option></term>
-<listitem><para>
-Lists the keys in <replaceable>SCHEMA</replaceable>.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>list-children</option></term>
-<listitem><para>
-Lists the children of <replaceable>SCHEMA</replaceable>.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>list-recursively</option></term>
-<listitem><para>
-Lists keys and values, recursively. If no <replaceable>SCHEMA</replaceable>
-is given, list keys in all schemas.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>help</option></term>
-<listitem><para>
-Prints help and exits.
-</para></listitem>
-</varlistentry>
-
-</variablelist>
-
-</refsect1>
-</refentry>

docs/reference/gio/io-scheduler.md

@@ -0,0 +1,20 @@
+Title: GIOScheduler
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 2007 Andrew Walton
+
+# GIOScheduler
+
+Schedules asynchronous I/O operations. `GIOScheduler` integrates
+into the main event loop ([struct@GLib.MainLoop]) and uses threads.
+
+Deprecated: 2.36: As of GLib 2.36, `GIOScheduler` is deprecated in favor of
+[struct@GLib.ThreadPool] and [class@Gio.Task].
+
+The `GIOScheduler` API is:
+ * [type@Gio.IOSchedulerJobFunc]
+ * [func@Gio.io_scheduler_push_job]
+ * [func@Gio.io_scheduler_cancel_all_jobs]
+ * [type@Gio.IOSchedulerJob]
+ * [method@Gio.IOSchedulerJob.send_to_mainloop]
+ * [method@Gio.IOSchedulerJob.send_to_mainloop_async]
+

docs/reference/gio/menu-exporter.md

@@ -0,0 +1,15 @@
+Title: GMenuModel Exporter
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 2011 Matthias Clasen
+
+# GMenuModel Exporter
+
+These functions support exporting a [class@Gio.MenuModel] on D-Bus. The D-Bus
+interface that is used is a private implementation detail.
+
+ * [method@Gio.DBusConnection.export_menu_model]
+ * [method@Gio.DBusConnection.unexport_menu_model]
+
+To access an exported [class@Gio.MenuModel] remotely, use
+[func@Gio.DBusMenuModel.get] to obtain a [class@Gio.DBusMenuModel].
+

docs/reference/gio/meson.build

@@ -1,236 +1,111 @@
-if get_option('gtk_doc')
+if get_option('man-pages').enabled()
-  subdir('gdbus-object-manager-example')
-  subdir('xml')
-
-  ignore_headers = [
-    'gdbus-2.0',
-    'inotify',
-    'kqueue',
-    'libasyncns',
-    'tests',
-    'win32',
-    'xdgmime',
-    'gappinfoprivate.h',
-    'gapplicationimpl.h',
-    'gasynchelper.h',
-    'gcontenttypeprivate.h',
-    'gcontextspecificgroup.h',
-    'gcredentialsprivate.h',
-    'gdbus-daemon-generated.h',
-    'gdbusactiongroup-private.h',
-    'gdbusauth.h',
-    'gdbusauthmechanismanon.h',
-    'gdbusauthmechanismexternal.h',
-    'gdbusauthmechanism.h',
-    'gdbusauthmechanismsha1.h',
-    'gdbusdaemon.h',
-    'gdbusprivate.h',
-    'gdelayedsettingsbackend.h',
-    'gdocumentportal.h',
-    'gdummyfile.h',
-    'gdummyproxyresolver.h',
-    'gdummytlsbackend.h',
-    'gfileattribute-priv.h',
-    'gfileinfo-priv.h',
-    'ghttpproxy.h',
-    'giomodule-priv.h',
-    'gioprivate.h',
-    'giowin32-afunix.h',
-    'giowin32-priv.h',
-    'gio_probes.h',
-    'gio_trace.h',
-    'gio-tool.h',
-    'glocaldirectorymonitor.h',
-    'glocalfileenumerator.h',
-    'glocalfile.h',
-    'glocalfileinfo.h',
-    'glocalfileinputstream.h',
-    'glocalfileiostream.h',
-    'glocalfilemonitor.h',
-    'glocalfileoutputstream.h',
-    'glocalvfs.h',
-    'gmemorymonitordbus.h',
-    'gmemorymonitorportal.h',
-    'gmountprivate.h',
-    'gnativevolumemonitor.h',
-    'gnetworkingprivate.h',
-    'gnetworkmonitorbase.h',
-    'gnetworkmonitornetlink.h',
-    'gnetworkmonitornm.h',
-    'gnetworkmonitorportal.h',
-    'gnotificationbackend.h',
-    'gnotification-private.h',
-    'gopenuriportal.h',
-    'gpollfilemonitor.h',
-    'gportalsupport.h',
-    'gpowerprofilemonitordbus.h',
-    'gpowerprofilemonitorportal.h',
-    'gproxyresolverportal.h',
-    'gregistrysettingsbackend.h',
-    'gresourcefile.h',
-    'gsandbox.h',
-    'gsettingsbackendinternal.h',
-    'gsettings-mapping.h',
-    'gsettingsschema-internal.h',
-    'gsocketinputstream.h',
-    'gsocketoutputstream.h',
-    'gsocks4aproxy.h',
-    'gsocks4proxy.h',
-    'gsocks5proxy.h',
-    'gsubprocesslauncher-private.h',
-    'gthreadedresolver.h',
-    'gtrashportal.h',
-    'gunionvolumemonitor.h',
-    'gunixmount.h',
-    'gunixresolver.h',
-    'gunixvolume.h',
-    'gunixvolumemonitor.h',
-    'gwin32networkmonitor.h',
-    'gwin32api-application-activation-manager.h',
-    'gwin32api-iterator.h',
-    'gwin32api-misc.h',
-    'gwin32api-package.h',
-    'gwin32api-storage.h',
-    'gwin32appinfo.h',
-    'gwin32file-sync-stream.h',
-    'gwin32mount.h',
-    'gwin32packageparser.h',
-    'gwin32resolver.h',
-    'gwin32volumemonitor.h',
-    'thumbnail-verify.h',
-    'xdp-dbus.h',
-    'gio-visibility.h',
-  ]
-
-  sections_files = files('gio-sections-common.txt')
-
-  if host_system == 'windows'
-    ignore_headers += [
-      'gfiledescriptorbased.h',
-      'gunixmounts.h',
-      'gunixfdmessage.h',
-      'gunixinputstream.h',
-      'gunixoutputstream.h',
-      'gdesktopappinfo.h',
-      'gosxappinfo.h',
-    ]
-    sections_files += files('gio-sections-win32.txt')
-    platform_file = files('gio-docs-win32.xml')
-  else
-    if glib_have_cocoa
-      ignore_headers += ['gdesktopappinfo.h']
-    else
-      ignore_headers += ['gosxappinfo.h']
-    endif
-
-    ignore_headers += [
-      'gwin32inputstream.h',
-      'gwin32outputstream.h',
-      'gwin32registrykey.h',
-    ]
-    platform_file = files('gio-docs-unix.xml')
-  endif
-
-  ignore_sources = [
-    'kqueue',
-    'tests',
-    'gdbus-daemon-generated.c',
-    'xdp-dbus.c',
-  ]
-
-  docpath = join_paths(glib_datadir, 'gtk-doc', 'html')
-  version_conf = configuration_data()
-  version_conf.set('VERSION', meson.project_version())
-  configure_file(
-    input: 'version.xml.in',
-    output: 'version.xml',
-    configuration: version_conf
-  )
-
-  concat_files_helper = find_program('concat-files-helper.py')
-  configure_file(
-    output : 'gio-sections.txt',
-    input : sections_files,
-    command : [concat_files_helper, '@OUTPUT@', '@INPUT@'],
-  )
-
-  configure_file(
-    output : 'gio-docs-platform.xml',
-    input : platform_file,
-    copy : true,
-  )
-
-  content_files = [
-    'overview.xml',
-    'migrating-posix.xml',
-    'migrating-gnome-vfs.xml',
-    'migrating-gconf.xml',
-    'migrating-gdbus.xml',
-    'gio-querymodules.xml',
-    'glib-compile-schemas.xml',
-    'glib-compile-resources.xml',
-    'gapplication.xml',
-    'gsettings.xml',
-    'gresource.xml',
-    'gdbus.xml',
-    'gdbus-codegen.xml',
-  ]
-
-  content_files += [
-    gdbus_example_objectmanager_xml,
-    gdbus_example_objectmanager_sources,
-    gdbus_object_manager_example_doc
-  ]
-
-  gnome.gtkdoc('gio',
-    main_xml : 'gio-docs.xml',
-    namespace : 'g',
-    mode : 'none',
-    dependencies : [libgio_dep, libgobject_dep, libglib_dep],
-    src_dir : 'gio',
-    scan_args : [
-      '--ignore-decorators=' + ignore_decorators.replace('GLIB', 'GIO'),
-      '--rebuild-types',
-      '--ignore-headers=' + ' '.join(ignore_headers),
-    ],
-    mkdb_args : [
-      '--ignore-files=' + ' '.join(ignore_sources),
-    ],
-    content_files : content_files,
-    expand_content_files : [
-      'overview.xml',
-      'migrating-posix.xml',
-      'migrating-gnome-vfs.xml',
-      'migrating-gconf.xml',
-      'migrating-gdbus.xml',
-      'gdbus-codegen.xml',
-    ],
-    html_assets : [
-      'gvfs-overview.png',
-      'menu-example.png',
-      'menu-model.png',
-    ],
-    fixxref_args: [
-      '--html-dir=' + docpath,
-      '--extra-dir=' + join_paths('gio', '..', 'glib', 'html'),
-      '--extra-dir=' + join_paths('gio', '..', 'gobject', 'html'),
-    ],
-    install: true,
-    check: true,
-  )
-endif
-
-
-if get_option('man')
   manpages = ['gapplication', 'gio-querymodules', 'glib-compile-schemas',
               'glib-compile-resources', 'gsettings', 'gresource', 'gdbus',
               'gio', 'gdbus-codegen']
   foreach page : manpages
     custom_target(page + '-man',
-      input: page + '.xml',
+      input: page + '.rst',
       output: page + '.1',
-      command: xsltproc_command,
+      command: [
+        rst2man,
+        rst2man_flags,
+        '@INPUT@',
+      ],
+      capture: true,
       install: true,
-      install_dir: man1_dir)
+      install_dir: man1_dir,
+      install_tag: 'doc',
+    )
   endforeach
 endif
+
+if get_option('documentation') and enable_gir
+  expand_content_files = [
+    'dbus-error.md',
+    'dbus-introspection.md',
+    'dbus-name-owning.md',
+    'dbus-name-watching.md',
+    'dbus-utils.md',
+    'error.md',
+    'file-attributes.md',
+    'io-scheduler.md',
+    'menu-exporter.md',
+    'migrating-gconf.md',
+    'migrating-gdbus.md',
+    'migrating-gnome-vfs.md',
+    'migrating-posix.md',
+    'networking.md',
+    'overview.md',
+    'pollable-utils.md',
+    'tls-overview.md',
+  ]
+  expand_content_unix_files = [
+    'unix-mounts.md',
+  ]
+  expand_content_win32_files = []
+
+  gio_toml = configure_file(input: 'gio.toml.in', output: 'gio.toml', configuration: toml_conf)
+
+  custom_target('gio-docs',
+    input: [ gio_toml, gio_gir[0] ],
+    output: 'gio',
+    command: [
+      gidocgen,
+      'generate',
+      gidocgen_common_args,
+      '--config=@INPUT0@',
+      '--output-dir=@OUTPUT@',
+      '--content-dir=@0@'.format(meson.current_source_dir()),
+      '@INPUT1@',
+    ],
+    build_by_default: true,
+    depend_files: expand_content_files,
+    install: true,
+    install_dir: docs_dir,
+    install_tag: 'doc',
+  )
+
+  if host_system == 'windows'
+    gio_win32_toml = configure_file(input: 'gio-win32.toml.in', output: 'gio-win32.toml', configuration: toml_conf)
+
+    custom_target('gio-win32-docs',
+      input: [ gio_win32_toml, gio_win32_gir[0] ],
+      output: 'gio-win32',
+      command: [
+        gidocgen,
+        'generate',
+        gidocgen_common_args,
+        '--config=@INPUT0@',
+        '--output-dir=@OUTPUT@',
+        '--content-dir=@0@'.format(meson.current_source_dir()),
+        '@INPUT1@',
+      ],
+      build_by_default: true,
+      depend_files: expand_content_win32_files,
+      install: true,
+      install_dir: docs_dir,
+      install_tag: 'doc',
+    )
+  else
+    gio_unix_toml = configure_file(input: 'gio-unix.toml.in', output: 'gio-unix.toml', configuration: toml_conf)
+
+    custom_target('gio-unix-docs',
+      input: [ gio_unix_toml, gio_unix_gir[0] ],
+      output: 'gio-unix',
+      command: [
+        gidocgen,
+        'generate',
+        gidocgen_common_args,
+        '--config=@INPUT0@',
+        '--output-dir=@OUTPUT@',
+        '--content-dir=@0@'.format(meson.current_source_dir()),
+        '@INPUT1@',
+      ],
+      build_by_default: true,
+      depend_files: expand_content_unix_files,
+      install: true,
+      install_dir: docs_dir,
+      install_tag: 'doc',
+    )
+  endif
+endif

docs/reference/gio/migrating-gconf.md

@@ -0,0 +1,466 @@
+Title: Migrating from GConf to GSettings
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 2010, 2012 Matthias Clasen
+SPDX-FileCopyrightText: 2010 Allison Lortie
+SPDX-FileCopyrightText: 2011 Ray Strode
+
+# Migrating from GConf to GSettings
+
+## Before you start
+
+Converting individual applications and their settings from GConf to
+GSettings can be done at will. But desktop-wide settings like font or theme
+settings often have consumers in multiple modules. Therefore, some
+consideration has to go into making sure that all users of a setting are
+converted to GSettings at the same time or that the program responsible for
+configuring that setting continues to update the value in both places.
+
+It is always a good idea to have a look at how others have handled similar
+problems before.
+
+## Conceptual differences
+
+Conceptually, GConf and GSettings are fairly similar. Both have a concept of
+pluggable backends. Both keep information about keys and their types in
+schemas. Both have a concept of mandatory values, which lets you implement
+lock-down.
+
+There are some differences in the approach to schemas. GConf installs the
+schemas into the database and has API to handle schema information
+(`gconf_client_get_default_from_schema()`, `gconf_value_get_schema()`, etc).
+GSettings on the other hand assumes that an application knows its own
+schemas, and does not provide API to handle schema information at runtime.
+GSettings is also more strict about requiring a schema whenever you want to
+read or write a key. To deal with more free-form information that would
+appear in schema-less entries in GConf, GSettings allows for schemas to be
+'relocatable'.
+
+One difference in the way applications interact with their settings is that
+with GConf you interact with a tree of settings (ie the keys you pass to
+functions when reading or writing values are actually paths with the actual
+name of the key as the last element. With GSettings, you create a GSettings
+object which has an implicit prefix that determines where the settings get
+stored in the global tree of settings, but the keys you pass when reading or
+writing values are just the key names, not the full path.
+
+## GConfClient (and GConfBridge) API conversion
+
+Most people use GConf via the high-level `GConfClient` API. The
+corresponding API is the [class@Gio.Settings] object. While not every
+`GConfClient` function has a direct GSettings equivalent, many do:
+
+| GConfClient | GSettings |
+|-------------|-----------|
+| `gconf_client_get_default()` | no direct equivalent, instead you call [`ctor@Gio.Settings.new`] for the schemas you use |
+| `gconf_client_set()` | [`method@Gio.Settings.set`] |
+| `gconf_client_get()` | `g_settings_get()` |
+| `gconf_client_get_bool()` | `g_settings_get_boolean()` |
+| `gconf_client_set_bool()` | `g_settings_set_boolean()` |
+| `gconf_client_get_int()` | `g_settings_get_int()` |
+| `gconf_client_set_int()` | `g_settings_set_int()` |
+| `gconf_client_get_float()` | `g_settings_get_double()` |
+| `gconf_client_set_float()` | `g_settings_set_double()` |
+| `gconf_client_get_string()` | `g_settings_get_string()` |
+| `gconf_client_set_string()` | `g_settings_set_string()` |
+| `gconf_client_get_list()` | for string lists, see `g_settings_get_strv()`, else see `g_settings_get_value()` and GVariant API |
+| `gconf_client_set_list()` | for string lists, see `g_settings_set_strv()`, else see `g_settings_set_value()` and GVariant API |
+| `gconf_entry_get_is_writable()` | `g_settings_is_writable()` |
+| `gconf_client_notify_add()` | not required, the “changed” signal is emitted automatically |
+| `gconf_client_add_dir()` | not required, each GSettings instance automatically watches all keys in its path |
+| `GConfChangeSet` | `g_settings_delay()`, `g_settings_apply()` |
+| `gconf_client_get_default_from_schema()` | no equivalent, applications are expected to know their schema |
+| `gconf_client_all_entries()` | no equivalent, applications are expected to know their schema, and GSettings does not allow schema-less entries |
+| `gconf_client_get_without_default()` | no equivalent |
+| `gconf_bridge_bind_property()` | `g_settings_bind()` |
+| `gconf_bridge_bind_property_full()` | `g_settings_bind_with_mapping()` |
+
+GConfBridge was a third-party library that used GConf to bind an object
+property to a particular configuration key. GSettings offers this service
+itself.
+
+There is a pattern that is sometimes used for GConf, where a setting can
+have explicit 'value A', explicit 'value B' or 'use the system default'.
+With GConf, 'use the system default' is sometimes implemented by unsetting
+the user value. This is not possible in GSettings, since it does not have
+API to determine if a value is the default and does not let you unset
+values. The recommended way (and much clearer) way in which this can be
+implemented in GSettings is to have a separate 'use-system-default' boolean
+setting.
+
+## Change notification
+
+GConf requires you to call `gconf_client_add_dir()` and
+`gconf_client_notify_add()` to get change notification. With GSettings, this
+is not necessary; signals get emitted automatically for every change.
+
+The [signal@Gio.Settings::changed] signal is emitted for each changed key.
+There is also a [`signal@Gio.Settings::change-event`] signal that you can
+handle if you need to see groups of keys that get changed at the same time.
+
+GSettings also notifies you about changes in writability of keys, with the
+[signal@Gio.Settings::writable-changed] signal (and the
+[signal@Gio.Settings::writable-change-event] signal).
+
+## Change sets
+
+GConf has a concept of a set of changes which can be applied or reverted at
+once: `GConfChangeSet` (GConf doesn't actually apply changes atomically,
+which is one of its shortcomings).
+
+Instead of a separate object to represent a change set, GSettings has a
+'delayed-apply' mode, which can be turned on for a [class@Gio.Settings]
+object by calling [method@Gio.Settings.delay]. In this mode, changes done to
+the GSettings object are not applied - they are still visible when calling
+[method@Gio.Settings.get] on the same object, but not to other GSettings
+instances or even other processes.
+
+To apply the pending changes all at once (GSettings does atomicity here),
+call [method@Gio.Settings.apply]. To revert the pending changes, call
+[method@Gio.Settings.revert] or just drop the reference to the GSettings
+object.
+
+## Schema conversion
+
+If you are porting your application from GConf, most likely you already have
+a GConf schema. GConf comes with a commandline tool
+`gsettings-schema-convert` that can help with the task of converting a GConf
+schema into an equivalent GSettings schema. The tool is not perfect and may
+need assistance in some cases.
+
+### An example for using gsettings-schema-convert
+
+Running `gsettings-schema-convert --gconf --xml --schema-id
+"org.gnome.font-rendering" --output org.gnome.font-rendering.gschema.xml
+destop_gnome_font_rendering.schemas` on the following
+`desktop_gnome_font_rendering.schemas` file:
+
+```xml
+<?xml version="1.0"?>
+<gconfschemafile>
+    <schemalist>
+        <schema>
+            <key>/schemas/desktop/gnome/font_rendering/dpi</key>
+            <applyto>/desktop/gnome/font_rendering/dpi</applyto>
+            <owner>gnome</owner>
+            <type>int</type>
+            <default>96</default>
+            <locale name="C">
+                <short>DPI</short>
+                <long>The resolution used for converting font sizes to pixel sizes, in dots per inch.</long>
+            </locale>
+        </schema>
+    </schemalist>
+</gconfschemafile>
+```
+
+produces an `org.gnome.font-rendering.gschema.xml` file with the following content:
+
+```xml
+<schemalist>
+  <schema id="org.gnome.font-rendering" path="/desktop/gnome/font_rendering/">
+    <key name="dpi" type="i">
+      <default>96</default>
+      <summary>DPI</summary>
+      <description>The resolution used for converting font sizes to pixel sizes, in dots per inch.</description>
+    </key>
+  </schema>
+</schemalist>
+```
+
+GSettings schemas are identified at runtime by their id (as specified in the
+XML source file). It is recommended to use a dotted name as schema id,
+similar in style to a D-Bus bus name, e.g. "org.gnome.SessionManager". In
+cases where the settings are general and not specific to one application,
+the id should not use StudlyCaps, e.g. "org.gnome.font-rendering". The
+filename used for the XML schema source is immaterial, but schema compiler
+expects the files to have the extension `.gschema.xml`. It is recommended to
+simply use the schema id as the filename, followed by this extension, e.g.
+`org.gnome.SessionManager.gschema.xml`.
+
+The XML source file for your GSettings schema needs to get installed into
+`$datadir/glib-2.0/schemas`, and needs to be compiled into a binary form. At
+runtime, GSettings looks for compiled schemas in the `glib-2.0/schemas`
+subdirectories of all `XDG_DATA_DIRS` directories, so if you install your
+schema in a different location, you need to set the `XDG_DATA_DIRS`
+environment variable appropriately.
+
+Schemas are compiled into binary form by the `glib-compile-schemas` utility.
+GIO provides a `glib_compile_schemas` variable in its pkg-config file
+pointing to the schema compiler binary.
+
+### Using schemas with Meson
+
+You should use `install_data()` to install the `.gschema.xml` file in the
+correct directory, e.g.
+
+```
+install_data('my.app.gschema.xml', install_dir: get_option('datadir') / 'glib-2.0/schemas')
+```
+
+Schema compilation is done at installation time; if you are using Meson 0.57 or newer, you can use the `gnome.post_install()` function from the GNOME module:
+
+```
+gnome.post_install(glib_compile_schemas: true)
+```
+
+Alternatively, you can use `meson.add_install_script()` and the following
+Python script:
+
+```py
+#!/usr/bin/env python3
+# build-aux/compile-schemas.py
+
+import os
+import subprocess
+
+install_prefix = os.environ['MESON_INSTALL_PREFIX']
+schemadir = os.path.join(install_prefix, 'share', 'glib-2.0', 'schemas')
+
+if not os.environ.get('DESTDIR'):
+    print('Compiling gsettings schemas...')
+    subprocess.call(['glib-compile-schemas', schemadir])
+```
+
+```
+meson.add_install_script('build-aux/compile-schemas.py')
+```
+
+### Using schemas with Autotools
+
+GLib provides m4 macros for hiding the various complexities and reduce the
+chances of getting things wrong.
+
+To handle schemas in your Autotools build, start by adding this to your
+`configure.ac`:
+
+```
+GLIB_GSETTINGS
+```
+
+Then add this fragment to your `Makefile.am`:
+
+```
+# gsettings_SCHEMAS is a list of all the schemas you want to install
+gsettings_SCHEMAS = my.app.gschema.xml
+
+# include the appropriate makefile rules for schema handling
+@GSETTINGS_RULES@
+```
+
+This is not sufficient on its own. You need to mention what the source of
+the `my.app.gschema.xml` file is. If the schema file is distributed directly
+with your project's tarball then a mention in `EXTRA_DIST` is appropriate. If
+the schema file is generated from another source then you will need the
+appropriate rule for that, plus probably an item in `EXTRA_DIST` for the
+source files used by that rule.
+
+One possible pitfall in doing schema conversion is that the default values
+in GSettings schemas are parsed by the GVariant parser. This means that
+strings need to include quotes in the XML. Also note that the types are now
+specified as GVariant type strings.
+
+```xml
+<type>string</type>
+<default>rgb</default>
+```
+
+becomes
+
+```xml
+<key name="rgba-order" type="s">
+  <default>'rgb'</default> <!-- note quotes -->
+</key>
+```
+
+Another possible complication is that GConf specifies full paths for each
+key, while a GSettings schema has a 'path' attribute that contains the
+prefix for all the keys in the schema, and individual keys just have a
+simple name. So
+
+```xml
+<key>/schemas/desktop/gnome/font_rendering/antialiasing</key>
+```
+
+becomes
+
+```xml
+<schema id="org.gnome.font" path="/desktop/gnome/font_rendering/">
+  <key name="antialiasing" type="s">
+```
+
+
+Default values can be localized in both GConf and GSettings schemas, but
+GSettings uses gettext for the localization. You can specify the gettext
+domain to use in the gettext-domain attribute. Therefore, when converting
+localized defaults in GConf,
+
+```xml
+<key>/schemas/apps/my_app/font_size</key>
+  <locale name="C">
+    <default>18</default>
+  </locale>
+  <locale name="be">
+    <default>24</default>
+  </locale>
+</key>
+```
+
+becomes
+
+```xml
+<schema id="..." gettext-domain="your-domain">
+ ...
+<key name="font-size" type="i">
+  <default l10n="messages" context="font_size">18</default>
+</key>
+```
+
+GSettings uses gettext for translation of default values. The string that is
+translated is exactly the string that appears inside of the `<default>`
+element. This includes the quotation marks that appear around strings.
+Default values must be marked with the l10n attribute in the `<default>` tag,
+which should be set as equal to 'messages' or 'time' depending on the
+desired category. An optional translation context can also be specified with
+the context attribute, as in the example. This is usually recommended, since
+the string "18" is not particularly easy to translate without context. The
+translated version of the default value should be stored in the specified
+gettext-domain. Care must be taken during translation to ensure that all
+translated values remain syntactically valid; mistakes here will cause
+runtime errors.
+
+GSettings schemas have optional `<summary>` and `<description>` elements for
+each key which correspond to the `<short>` and `<long>` elements in the
+GConf schema and can be used in the same way by a GUI editor, so you should
+use the same conventions for them: The summary is just a short label with no
+punctuation, the description can be one or more complete sentences. If
+multiple paragraphs are desired for the description, the paragraphs should
+be separated by a completely empty line.
+
+Translations for these strings will also be handled via gettext, so you
+should arrange for these strings to be extracted into your gettext catalog.
+Gettext supports GSettings schemas natively since version 0.19, so all you
+have to do is add the XML schema file to the list of translatable files
+inside your `POTFILES.in`.
+
+GSettings is a bit more restrictive about key names than GConf. Key names in
+GSettings can be at most 32 characters long, and must only consist of
+lowercase characters, numbers and dashes, with no consecutive dashes. The
+first character must not be a number or dash, and the last character cannot
+be '-'.
+
+If you are using the GConf backend for GSettings during the transition, you
+may want to keep your key names the same they were in GConf, so that
+existing settings in the users GConf database are preserved. You can achieve
+this by using the `--allow-any-name` with the `glib-compile-schemas` schema
+compiler. Note that this option is only meant to ease the process of porting
+your application, allowing parts of your application to continue to access
+GConf and parts to use GSettings. By the time you have finished porting your
+application you must ensure that all key names are valid.
+
+## Data conversion
+
+GConf comes with a GSettings backend that can be used to facility the
+transition to the GSettings API until you are ready to make the jump to a
+different backend (most likely dconf). To use it, you need to set the
+`GSETTINGS_BACKEND` to 'gconf', e.g. by using
+
+```c
+g_setenv ("GSETTINGS_BACKEND", "gconf", TRUE);
+```
+
+early on in your program. Note that this backend is meant purely as a
+transition tool, and should not be used in production.
+
+GConf also comes with a utility called `gsettings-data-convert`, which is
+designed to help with the task of migrating user settings from GConf into
+another GSettings backend. It can be run manually, but it is designed to be
+executed automatically, every time a user logs in. It keeps track of the
+data migrations that it has already done, and it is harmless to run it more
+than once.
+
+To make use of this utility, you must install a keyfile in the directory
+`/usr/share/GConf/gsettings` which lists the GSettings keys and GConf paths
+to map to each other, for each schema that you want to migrate user data
+for.
+
+Here is an example:
+
+```
+[org.gnome.fonts]
+antialiasing = /desktop/gnome/font_rendering/antialiasing
+dpi = /desktop/gnome/font_rendering/dpi
+hinting = /desktop/gnome/font_rendering/hinting
+rgba-order = /desktop/gnome/font_rendering/rgba_order
+
+[apps.myapp:/path/to/myapps/]
+some-odd-key1 = /apps/myapp/some_ODD-key1
+```
+
+The last key demonstrates that it may be necessary to modify the key name to
+comply with stricter GSettings key name rules. Of course, that means your
+application must use the new key names when looking up settings in
+GSettings.
+
+The last group in the example also shows how to handle the case of
+'relocatable' schemas, which don't have a fixed path. You can specify the
+path to use in the group name, separated by a colon.
+
+There are some limitations: `gsettings-data-convert` does not do any
+transformation of the values. And it does not handle complex GConf types
+other than lists of strings or integers.
+
+**Don't forget to require GConf 2.31.1 or newer in your configure script if
+you are making use of the GConf backend or the conversion utility.**
+
+If, as an application developer, you are interested in manually ensuring
+that `gsettings-data-convert` has been invoked (for example, to deal with the
+case where the user is logged in during a distribution upgrade or for
+non-XDG desktop environments which do not run the command as an autostart)
+you may invoke it manually during your program initialisation. This is not
+recommended for all application authors -- it is your choice if this use
+case concerns you enough.
+
+Internally, `gsettings-data-convert` uses a keyfile to track which settings
+have been migrated. The following code fragment will check that keyfile to
+see if your data conversion script has been run yet and, if not, will
+attempt to invoke the tool to run it. You should adapt it to your
+application as you see fit.
+
+```c
+static void
+ensure_migrated (const gchar *name)
+{
+  gboolean needed = TRUE;
+  GKeyFile *kf;
+  gchar **list;
+  gsize i, n;
+
+  kf = g_key_file_new ();
+
+  g_key_file_load_from_data_dirs (kf, "gsettings-data-convert",
+                                  NULL, G_KEY_FILE_NONE, NULL);
+  list = g_key_file_get_string_list (kf, "State", "converted", &n, NULL);
+
+  if (list)
+    {
+      for (i = 0; i < n; i++)
+        if (strcmp (list[i], name) == 0)
+          {
+            needed = FALSE;
+            break;
+          }
+
+      g_strfreev (list);
+    }
+
+  g_key_file_free (kf);
+
+  if (needed)
+    g_spawn_command_line_sync ("gsettings-data-convert",
+                               NULL, NULL, NULL, NULL);
+}
+```
+
+Although there is the possibility that the `gsettings-data-convert` script
+will end up running multiple times concurrently with this approach, it is
+believed that this is safe.

docs/reference/gio/migrating-gconf.xml

@@ -1,515 +0,0 @@
-  <chapter>
-    <title>Migrating from GConf to GSettings</title>
-
-    <section>
-      <title>Before you start</title>
-
-      <para>
-        Converting individual applications and their settings from GConf to
-        GSettings can be done at will. But desktop-wide settings like font or
-        theme settings often have consumers in multiple modules. Therefore,
-        some consideration has to go into making sure that all users of a setting
-        are converted to GSettings at the same time or that the program
-        responsible for configuring that setting continues to update the value in
-        both places.
-      </para>
-      <para>
-        It is always a good idea to have a look at how others have handled
-        similar problems before.
-      </para>
-    </section>
-
-    <section>
-      <title>Conceptual differences</title>
-
-      <para>
-        Conceptually, GConf and GSettings are fairly similar. Both
-        have a concept of pluggable backends. Both keep information
-        about keys and their types in schemas. Both have a concept of
-        mandatory values, which lets you implement lock-down.
-      </para>
-      <para>
-        There are some differences in the approach to schemas. GConf
-        installs the schemas into the database and has API to handle
-        schema information (gconf_client_get_default_from_schema(),
-        gconf_value_get_schema(), etc). GSettings on the other hand
-        assumes that an application knows its own schemas, and does
-        not provide API to handle schema information at runtime.
-        GSettings is also more strict about requiring a schema whenever
-        you want to read or write a key. To deal with more free-form
-        information that would appear in schema-less entries in GConf,
-        GSettings allows for schemas to be 'relocatable'.
-      </para>
-      <para>
-        One difference in the way applications interact with their
-        settings is that with GConf you interact with a tree of
-        settings (ie the keys you pass to functions when reading
-        or writing values are actually paths with the actual name
-        of the key as the last element. With GSettings, you create
-        a GSettings object which has an implicit prefix that determines
-        where the settings get stored in the global tree of settings,
-        but the keys you pass when reading or writing values are just
-        the key names, not the full path.
-      </para>
-    </section>
-
-    <section>
-      <title>GConfClient (and GConfBridge) API conversion</title>
-
-      <para>
-        Most people use GConf via the high-level #GConfClient API.
-        The corresponding API is the #GSettings object. While not
-        every GConfClient function has a direct GSettings equivalent,
-        many do:
-        <table id="gconf-client-vs-gsettings">
-          <tgroup cols="2">
-            <thead>
-              <row><entry>GConfClient</entry><entry>GSettings</entry></row>
-            </thead>
-            <tbody>
-              <row><entry>gconf_client_get_default()</entry><entry>no direct equivalent,
-                                                                   instead you call g_settings_new() for the schemas you use</entry></row>
-              <row><entry>gconf_client_set()</entry><entry>g_settings_set()</entry></row>
-              <row><entry>gconf_client_get()</entry><entry>g_settings_get()</entry></row>
-              <row><entry>gconf_client_get_bool()</entry><entry>g_settings_get_boolean()</entry></row>
-              <row><entry>gconf_client_set_bool()</entry><entry>g_settings_set_boolean()</entry></row>
-              <row><entry>gconf_client_get_int()</entry><entry>g_settings_get_int()</entry></row>
-              <row><entry>gconf_client_set_int()</entry><entry>g_settings_set_int()</entry></row>
-              <row><entry>gconf_client_get_float()</entry><entry>g_settings_get_double()</entry></row>
-              <row><entry>gconf_client_set_float()</entry><entry>g_settings_set_double()</entry></row>
-              <row><entry>gconf_client_get_string()</entry><entry>g_settings_get_string()</entry></row>
-              <row><entry>gconf_client_set_string()</entry><entry>g_settings_set_string()</entry></row>
-              <row><entry>gconf_client_get_list()</entry><entry>for string lists, see g_settings_get_strv(), else see g_settings_get_value() and #GVariant API</entry></row>
-              <row><entry>gconf_client_set_list()</entry><entry>for string lists, see g_settings_set_strv(), else see g_settings_set_value() and #GVariant API</entry></row>
-              <row><entry>gconf_entry_get_is_writable()</entry><entry>g_settings_is_writable()</entry></row>
-              <row><entry>gconf_client_notify_add()</entry><entry>not required, the #GSettings::changed signal is emitted automatically</entry></row>
-              <row><entry>gconf_client_add_dir()</entry><entry>not required, each GSettings instance automatically watches all keys in its path</entry></row>
-              <row><entry>#GConfChangeSet</entry><entry>g_settings_delay(), g_settings_apply()</entry></row>
-              <row><entry>gconf_client_get_default_from_schema()</entry><entry>no equivalent, applications are expected to know their schema</entry></row>
-              <row><entry>gconf_client_all_entries()</entry><entry>no equivalent, applications are expected to know their schema, and GSettings does not allow schema-less entries</entry></row>
-              <row><entry>gconf_client_get_without_default()</entry><entry>no equivalent</entry></row>
-              <row><entry>gconf_bridge_bind_property()</entry><entry>g_settings_bind()</entry></row>
-              <row><entry>gconf_bridge_bind_property_full()</entry><entry>g_settings_bind_with_mapping()</entry></row>
-            </tbody>
-          </tgroup>
-        </table>
-      </para>
-      <para>
-        GConfBridge was a third-party library that used GConf to bind an object property
-        to a particular configuration key. GSettings offers this service itself.
-      </para>
-      <para>
-        There is a pattern that is sometimes used for GConf, where a setting can have
-        explicit 'value A', explicit 'value B' or 'use the system default'. With GConf,
-        'use the system default' is sometimes implemented by unsetting the user value.
-      </para>
-      <para>
-        This is not possible in GSettings, since it does not have API to determine if a value
-        is the default and does not let you unset values. The recommended way (and much
-        clearer) way in which this can be implemented in GSettings is to have a separate
-        'use-system-default' boolean setting.
-      </para>
-    </section>
-
-    <section>
-      <title>Change notification</title>
-
-      <para>
-        GConf requires you to call gconf_client_add_dir() and
-        gconf_client_notify_add() to get change notification. With
-        GSettings, this is not necessary; signals get emitted automatically
-        for every change.
-      </para>
-      <para>
-        The #GSettings::changed signal is emitted for each changed key.
-        There is also a #GSettings::change-event signal that you can handle
-        if you need to see groups of keys that get changed at the same time.
-      </para>
-      <para>
-        GSettings also notifies you about changes in writability of keys,
-        with the #GSettings::writable-changed signal (and the
-        #GSettings::writable-change-event signal).
-      </para>
-    </section>
-
-    <section><title>Change sets</title>
-      <para>
-        GConf has a concept of a set of changes which can be applied or reverted
-        at once: #GConfChangeSet (GConf doesn't actually apply changes atomically,
-        which is one of its shortcomings).
-      </para>
-      <para>
-        Instead of a separate object to represent a change set, GSettings has a
-        'delayed-apply' mode, which can be turned on for a GSettings object by
-        calling g_settings_delay(). In this mode, changes done to the GSettings
-        object are not applied - they are still visible when calling g_settings_get()
-        <emphasis>on the same object</emphasis>, but not to other GSettings instances
-        or even other processes.
-      </para>
-      <para>
-        To apply the pending changes all at once (GSettings <emphasis>does</emphasis>
-        atomicity here), call g_settings_apply(). To revert the pending changes,
-        call g_settings_revert() or just drop the reference to the #GSettings object.
-      </para>
-    </section>
-
-    <section>
-      <title>Schema conversion</title>
-
-      <para>
-        If you are porting your application from GConf, most likely you already
-        have a GConf schema. GConf comes with a commandline tool
-        gsettings-schema-convert that can help with the task of converting
-        a GConf schema into an equivalent GSettings schema. The tool is not
-        perfect and may need assistance in some cases.
-      </para>
-      <example><title>An example for using gsettings-schema-convert</title>
-        <para>Running <userinput>gsettings-schema-convert --gconf --xml --schema-id "org.gnome.font-rendering" --output org.gnome.font-rendering.gschema.xml destop_gnome_font_rendering.schemas</userinput> on the following <filename>desktop_gnome_font_rendering.schemas</filename> file:
-        <programlisting>
-<![CDATA[
-<?xml version="1.0"?>
-<gconfschemafile>
-    <schemalist>
-        <schema>
-            <key>/schemas/desktop/gnome/font_rendering/dpi</key>
-            <applyto>/desktop/gnome/font_rendering/dpi</applyto>
-            <owner>gnome</owner>
-            <type>int</type>
-            <default>96</default>
-            <locale name="C">
-                <short>DPI</short>
-                <long>The resolution used for converting font sizes to pixel sizes, in dots per inch.</long>
-            </locale>
-        </schema>
-    </schemalist>
-</gconfschemafile>
-]]>
-</programlisting>
-produces a <filename>org.gnome.font-rendering.gschema.xml</filename> file with the following content:
-<programlisting>
-<![CDATA[
-<schemalist>
-  <schema id="org.gnome.font-rendering" path="/desktop/gnome/font_rendering/">
-    <key name="dpi" type="i">
-      <default>96</default>
-      <summary>DPI</summary>
-      <description>The resolution used for converting font sizes to pixel sizes, in dots per inch.</description>
-    </key>
-  </schema>
-</schemalist>
-]]>
-</programlisting>
-</para>
-      </example>
-
-      <para>
-       GSettings schemas are identified at runtime by their id (as specified
-       in the XML source file). It is recommended to use a dotted name as schema
-       id, similar in style to a D-Bus bus name, e.g. "org.gnome.SessionManager".
-       In cases where the settings are general and not specific to one application,
-       the id should not use StudlyCaps, e.g. "org.gnome.font-rendering".
-       The filename used for the XML schema source is immaterial, but
-       schema compiler expects the files to have the extension
-       <filename>.gschema.xml</filename>. It is recommended to simply
-       use the schema id as the filename, followed by this extension,
-       e.g. <filename>org.gnome.SessionManager.gschema.xml</filename>.
-      </para>
-
-      <para>
-        The XML source file for your GSettings schema needs to get installed
-        into <filename>$datadir/glib-2.0/schemas</filename>, and needs to be
-        compiled into a binary form. At runtime, GSettings looks for compiled
-        schemas in the <filename>glib-2.0/schemas</filename> subdirectories
-        of all <envar>XDG_DATA_DIRS</envar> directories, so if you install
-        your schema in a different location, you need to set the
-        <envar>XDG_DATA_DIRS</envar> environment variable appropriately.
-      </para>
-      <para>
-        Schemas are compiled into binary form by the
-        <link linkend="glib-compile-schemas">glib-compile-schemas</link> utility.
-        GIO provides a <literal>glib_compile_schemas</literal>
-        variable for the schema compiler.
-      </para>
-      <para>
-        You can ignore all of this by using the provided m4 macros.  To
-        do this, add to your <filename>configure.ac</filename>:
-<programlisting>
-GLIB_GSETTINGS
-</programlisting>
-        The corresponding <filename>Makefile.am</filename> fragment looks like
-        this:
-<programlisting>
-# gsettings_SCHEMAS is a list of all the schemas you want to install
-gsettings_SCHEMAS = my.app.gschema.xml
-
-# include the appropriate makefile rules for schema handling
-@GSETTINGS_RULES@
-</programlisting>
-      </para>
-
-      <para>
-        This is not sufficient on its own.  You need to mention what the source
-        of the <filename>my.app.gschema.xml</filename> file is.  If the schema
-        file is distributed directly with your project's tarball then a mention
-        in <varname>EXTRA_DIST</varname> is appropriate.  If the schema file is
-        generated from another source then you will need the appropriate rule
-        for that, plus probably an item in <varname>EXTRA_DIST</varname> for the
-        source files used by that rule.
-      </para>
-
-      <para>
-        One possible pitfall in doing schema conversion is that the default
-        values in GSettings schemas are parsed by the #GVariant parser.
-        This means that strings need to include quotes in the XML.  Also note
-        that the types are now specified as #GVariant type strings.
-        <programlisting>
-<![CDATA[
-<type>string</type>
-<default>rgb</default>
-]]>
-        </programlisting>
-        becomes
-        <programlisting>
-<![CDATA[
-<key name="rgba-order" type="s">
-  <default>'rgb'</default> <!-- note quotes -->
-</key>
-]]>
-        </programlisting>
-      </para>
-      <para>
-        Another possible complication is that GConf specifies full paths
-        for each key, while a GSettings schema has a 'path' attribute that
-        contains the prefix for all the keys in the schema, and individual
-        keys just have a simple name. So
-        <programlisting>
-<![CDATA[
-<key>/schemas/desktop/gnome/font_rendering/antialiasing</key>
-]]>
-        </programlisting>
-        becomes
-        <programlisting>
-<![CDATA[
-<schema id="org.gnome.font" path="/desktop/gnome/font_rendering/">
-  <key name="antialiasing" type="s">
-]]>
-        </programlisting>
-      </para>
-      <para>
-        Default values can be localized in both GConf and GSettings schemas,
-        but GSettings uses gettext for the localization. You can specify
-        the gettext domain to use in the <tag class="attribute">gettext-domain</tag>
-        attribute. Therefore, when converting localized defaults in GConf,
-        <programlisting>
-<![CDATA[
-<key>/schemas/apps/my_app/font_size</key>
-  <locale name="C">
-    <default>18</default>
-  </locale>
-  <locale name="be">
-    <default>24</default>
-  </locale>
-</key>
-]]>
-        </programlisting>
-        becomes
-        <programlisting>
-<![CDATA[
-<schema id="..." gettext-domain="your-domain">
- ...
-<key name="font-size" type="i">
-  <default l10n="messages" context="font_size">18</default>
-</key>
-]]>
-        </programlisting>
-      </para>
-      <para>
-        GSettings uses gettext for translation of default values.
-        The string that is translated is exactly the string that appears
-        inside of the <tag class='starttag'>default</tag> element.  This
-        includes the quotation marks that appear around strings.
-        Default values must be marked with the <varname>l10n</varname>
-        attribute in the <tag class='starttag'>default</tag> tag, which
-        should be set as equal to <literal>'messages'</literal> or
-        <literal>'time'</literal> depending on the desired category.  An
-        optional translation context can also be specified with the
-        <varname>context</varname> attribute, as in the example.  This
-        is usually recommended, since the string "<literal>18</literal>"
-        is not particularly easy to translate without context.  The
-        translated version of the default value should be stored in the
-        specified <varname>gettext-domain</varname>.  Care must be taken
-        during translation to ensure that all translated values remain
-        syntactically valid; mistakes here will cause runtime errors.
-      </para>
-      <para>
-        GSettings schemas have optional <tag class="starttag">summary</tag> and
-        <tag class="starttag">description</tag> elements for each key which
-        correspond to the <tag class="starttag">short</tag> and
-        <tag class="starttag">long</tag> elements in the GConf schema and
-        will be used in similar ways by a future gsettings-editor, so you
-        should use the same conventions for them: The summary is just a short
-        label with no punctuation, the description can be one or more complete
-        sentences. If multiple paragraphs are desired for the description, the
-        paragraphs should be separated by a completely empty line.
-      </para>
-      <para>
-        Translations for these strings will also be handled
-        via gettext, so you should arrange for these strings to be
-        extracted into your gettext catalog. One way to do that is to use
-        intltool. Since intltool 0.50.1, schema files are
-        supported, so all you have to do is to add your .gschema.xml
-        files to <filename>POTFILES.in</filename> with a line like
-        <programlisting>
-        [type: gettext/gsettings]data/org.foo.MyApp.gschema.xml
-        </programlisting>
-      </para>
-      <para>
-        GSettings is a bit more restrictive about key names than GConf. Key
-        names in GSettings can be at most 32 characters long, and must only
-        consist of lowercase characters, numbers and dashes, with no
-        consecutive dashes. The first character must not be a number or dash,
-        and the last character cannot be '-'.
-      </para>
-      <para>
-        If you are using the GConf backend for GSettings during the
-        transition, you may want to keep your key names the same they
-        were in GConf, so that existing settings in the users GConf
-        database are preserved. You can achieve this by using the
-        <option>--allow-any-name</option> with the
-        <link linkend="glib-compile-schemas">glib-compile-schemas</link> schema
-        compiler. Note that this option is only meant
-        to ease the process of porting your application, allowing parts
-        of your application to continue to access GConf and parts to use
-        GSettings. By the time you have finished porting your application
-        you must ensure that all key names are valid.
-      </para>
-    </section>
-
-    <section><title>Data conversion</title>
-      <para>
-        GConf comes with a GSettings backend that can be used to
-        facility the transition to the GSettings API until you are
-        ready to make the jump to a different backend (most likely
-        dconf). To use it, you need to set the <envar>GSETTINGS_BACKEND</envar>
-        to 'gconf', e.g. by using
-<programlisting>
-  g_setenv ("GSETTINGS_BACKEND", "gconf", TRUE);
-</programlisting>
-        early on in your program. Note that this backend is meant purely
-        as a transition tool, and should not be used in production.
-      </para>
-      <para>
-        GConf also comes with a utility called
-        <command>gsettings-data-convert</command>, which is designed to help
-        with the task of migrating user settings from GConf into another
-        GSettings backend. It can be run manually, but it is designed to be
-        executed automatically, every time a user logs in. It keeps track of
-        the data migrations that it has already done, and it is harmless to
-        run it more than once.
-      </para>
-      <para>
-        To make use of this utility, you must install a keyfile in the
-        directory <filename>/usr/share/GConf/gsettings</filename> which
-        lists the GSettings keys and GConf paths to map to each other, for
-        each schema that you want to migrate user data for.
-      </para>
-      <para>
-        Here is an example:
-        <programlisting>
-<![CDATA[
-[org.gnome.fonts]
-antialiasing = /desktop/gnome/font_rendering/antialiasing
-dpi = /desktop/gnome/font_rendering/dpi
-hinting = /desktop/gnome/font_rendering/hinting
-rgba-order = /desktop/gnome/font_rendering/rgba_order
-
-[apps.myapp:/path/to/myapps/]
-some-odd-key1 = /apps/myapp/some_ODD-key1
-]]>
-        </programlisting>
-        The last key demonstrates that it may be necessary to modify the key
-        name to comply with stricter GSettings key name rules. Of course,
-        that means your application must use the new key names when looking
-        up settings in GSettings.
-      </para>
-      <para>
-        The last group in the example also shows how to handle the case
-        of 'relocatable' schemas, which don't have a fixed path. You can
-        specify the path to use in the group name, separated by a colon.
-      </para>
-      <para>
-        There are some limitations: <command>gsettings-data-convert</command>
-        does not do any transformation of the values. And it does not handle
-        complex GConf types other than lists of strings or integers.
-      </para>
-      <para>
-        Don't forget to require GConf 2.31.1 or newer in your configure
-        script if you are making use of the GConf backend or the conversion
-        utility.
-      </para>
-
-      <para>
-        If, as an application developer, you are interested in manually
-        ensuring that <command>gsettings-data-convert</command> has been
-        invoked (for example, to deal with the case where the user is
-        logged in during a distribution upgrade or for non-XDG desktop
-        environments which do not run the command as an autostart) you
-        may invoke it manually during your program initialisation.  This
-        is not recommended for all application authors -- it is your
-        choice if this use case concerns you enough.
-      </para>
-      <para>
-        Internally, <command>gsettings-data-convert</command> uses a
-        keyfile to track which settings have been migrated.  The
-        following code fragment will check that keyfile to see if your
-        data conversion script has been run yet and, if not, will
-        attempt to invoke the tool to run it.  You should adapt it to
-        your application as you see fit.
-      </para>
-      <para>
-        <programlisting>
-<![CDATA[
-static void
-ensure_migrated (const gchar *name)
-{
-  gboolean needed = TRUE;
-  GKeyFile *kf;
-  gchar **list;
-  gsize i, n;
-
-  kf = g_key_file_new ();
-
-  g_key_file_load_from_data_dirs (kf, "gsettings-data-convert",
-                                  NULL, G_KEY_FILE_NONE, NULL);
-  list = g_key_file_get_string_list (kf, "State", "converted", &n, NULL);
-
-  if (list)
-    {
-      for (i = 0; i < n; i++)
-        if (strcmp (list[i], name) == 0)
-          {
-            needed = FALSE;
-            break;
-          }
-
-      g_strfreev (list);
-    }
-
-  g_key_file_free (kf);
-
-  if (needed)
-    g_spawn_command_line_sync ("gsettings-data-convert",
-                               NULL, NULL, NULL, NULL);
-}
-
-]]>
-        </programlisting>
-      </para>
-      <para>
-        Although there is the possibility that the
-        <command>gsettings-data-convert</command> script will end up
-        running multiple times concurrently with this approach, it is
-        believed that this is safe.
-      </para>
-    </section>
-  </chapter>

docs/reference/gio/migrating-gdbus.md

@@ -0,0 +1,633 @@
+Title: Migrating to GDBus
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 2010 Matthias Clasen
+SPDX-FileCopyrightText: 2010, 2011 David Zeuthen
+
+# Migrating to GDBus
+
+## Conceptual differences
+
+The central concepts of D-Bus are modelled in a very similar way in
+dbus-glib and GDBus. Both have objects representing connections, proxies and
+method invocations. But there are some important differences:
+
+- dbus-glib uses the libdbus reference implementation, GDBus doesn't.
+  Instead, it relies on GIO streams as transport layer, and has its own
+  implementation for the D-Bus connection setup and authentication. Apart
+  from using streams as transport, avoiding libdbus also lets GDBus avoid
+  some thorny multithreading issues.
+- dbus-glib uses the GObject type system for method arguments and return
+  values, including a homegrown container specialization mechanism. GDBus
+  relies on the GVariant type system which is explicitly designed to match
+  D-Bus types.
+- dbus-glib models only D-Bus interfaces and does not provide any types for
+  objects. GDBus models both D-Bus interfaces (via the GDBusInterface,
+  GDBusProxy and GDBusInterfaceSkeleton types) and objects (via the
+  GDBusObject, GDBusObjectSkeleton and GDBusObjectProxy types).
+- GDBus includes native support for the org.freedesktop.DBus.Properties (via
+  the GDBusProxy type) and org.freedesktop.DBus.ObjectManager D-Bus
+  interfaces, dbus-glib doesn't.
+- The typical way to export an object in dbus-glib involves generating glue
+  code from XML introspection data using dbus-binding-tool. GDBus provides a
+  similar tool called gdbus-codegen that can also generate Docbook D-Bus
+  interface documentation.
+- dbus-glib doesn't provide any convenience API for owning and watching bus
+  names, GDBus provides the `g_bus_own_name()` and `g_bus_watch_name()`
+  family of convenience functions.
+- GDBus provides API to parse, generate and work with Introspection XML,
+  dbus-glib doesn't.
+- GTestDBus provides API to create isolated unit tests
+
+## API comparison
+
+| dbus-glib | GDBus |
+|-----------|-------|
+| `DBusGConnection` | `GDBusConnection` |
+| `DBusGProxy` | `GDBusProxy`, `GDBusInterface` - also see `GDBusObjectProxy` |
+| `DBusGObject` | `GDBusInterfaceSkeleton`, `GDBusInterface` - also see `GDBusObjectSkeleton` |
+| `DBusGMethodInvocation` | `GDBusMethodInvocation` |
+| `dbus_g_bus_get()` | `g_bus_get_sync()`, also see `g_bus_get()` |
+| `dbus_g_proxy_new_for_name()` | `g_dbus_proxy_new_sync()` and `g_dbus_proxy_new_for_bus_sync()`, also see `g_dbus_proxy_new()` |
+| `dbus_g_proxy_add_signal()` | not needed, use the generic “g-signal” |
+| `dbus_g_proxy_connect_signal()` | use `g_signal_connect()` with “g-signal” |
+| `dbus_g_connection_register_g_object()` | `g_dbus_connection_register_object()` - also see `g_dbus_object_manager_server_export()` |
+| `dbus_g_connection_unregister_g_object()` | `g_dbus_connection_unregister_object()` - also see `g_dbus_object_manager_server_unexport()` |
+| `dbus_g_object_type_install_info()` | introspection data is installed while registering an object, see `g_dbus_connection_register_object()` |
+| `dbus_g_proxy_begin_call()` | `g_dbus_proxy_call()` |
+| `dbus_g_proxy_end_call()` | `g_dbus_proxy_call_finish()` |
+| `dbus_g_proxy_call()` | `g_dbus_proxy_call_sync()` |
+| `dbus_g_error_domain_register()` | `g_dbus_error_register_error_domain()` |
+| `dbus_g_error_has_name()` | no direct equivalent, see `g_dbus_error_get_remote_error()` |
+| `dbus_g_method_return()` | `g_dbus_method_invocation_return_value()` |
+| `dbus_g_method_return_error()` | `g_dbus_method_invocation_return_error()` and variants |
+| `dbus_g_method_get_sender()` | `g_dbus_method_invocation_get_sender()` |
+
+## Owning bus names
+
+Using dbus-glib, you typically call RequestName manually to own a name, like in the following excerpt:
+
+```c
+error = NULL;
+res = dbus_g_proxy_call (system_bus_proxy,
+                         "RequestName",
+                         &error,
+                         G_TYPE_STRING, NAME_TO_CLAIM,
+                         G_TYPE_UINT,   DBUS_NAME_FLAG_ALLOW_REPLACEMENT,
+                         G_TYPE_INVALID,
+                         G_TYPE_UINT,   &result,
+                         G_TYPE_INVALID);
+if (!res)
+  {
+    if (error != NULL)
+      {
+        g_warning ("Failed to acquire %s: %s",
+                   NAME_TO_CLAIM, error->message);
+        g_error_free (error);
+      }
+    else
+      {
+        g_warning ("Failed to acquire %s", NAME_TO_CLAIM);
+      }
+    goto out;
+  }
+
+if (result != DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER)
+  {
+    if (error != NULL)
+      {
+        g_warning ("Failed to acquire %s: %s",
+                   NAME_TO_CLAIM, error->message);
+        g_error_free (error);
+      }
+    else
+      {
+        g_warning ("Failed to acquire %s", NAME_TO_CLAIM);
+      }
+    exit (1);
+  }
+
+dbus_g_proxy_add_signal (system_bus_proxy, "NameLost",
+                         G_TYPE_STRING, G_TYPE_INVALID);
+dbus_g_proxy_connect_signal (system_bus_proxy, "NameLost",
+                             G_CALLBACK (on_name_lost), NULL, NULL);
+
+/* further setup ... */
+```
+
+While you can do things this way with GDBus too, using
+`g_dbus_proxy_call_sync()`, it is much nicer to use the high-level API for
+this:
+
+```c
+static void
+on_name_acquired (GDBusConnection *connection,
+                  const gchar     *name,
+                  gpointer         user_data)
+{
+  /* further setup ... */
+}
+
+/* ... */
+
+  owner_id = g_bus_own_name (G_BUS_TYPE_SYSTEM,
+                             NAME_TO_CLAIM,
+                             G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT,
+                             on_bus_acquired,
+                             on_name_acquired,
+                             on_name_lost,
+                             NULL,
+                             NULL);
+
+  g_main_loop_run (loop);
+
+  g_bus_unown_name (owner_id);
+```
+
+Note that `g_bus_own_name()` works asynchronously and requires you to enter
+your mainloop to await the `on_name_aquired()` callback. Also note that in
+order to avoid race conditions (e.g. when your service is activated by a
+method call), you have to export your manager object before acquiring the
+name. The `on_bus_acquired()` callback is the right place to do such
+preparations.
+
+## Creating proxies for well-known names
+
+dbus-glib lets you create proxy objects for well-known names, like the following example:
+
+```c
+proxy = dbus_g_proxy_new_for_name (system_bus_connection,
+                                   "org.freedesktop.Accounts",
+                                   "/org/freedesktop/Accounts",
+                                   "org.freedesktop.Accounts");
+```
+
+For a DBusGProxy constructed like this, method calls will be sent to the current owner of the name, and that owner can change over time.
+
+The same can be achieved with GDBusProxy:
+
+```c
+error = NULL;
+proxy = g_dbus_proxy_new_for_bus_sync (G_BUS_TYPE_SYSTEM,
+                                       G_DBUS_PROXY_FLAGS_NONE,
+                                       NULL, /* GDBusInterfaceInfo */
+                                       "org.freedesktop.Accounts",
+                                       "/org/freedesktop/Accounts",
+                                       "org.freedesktop.Accounts",
+                                       NULL, /* GCancellable */
+                                       &error);
+```
+
+For an added layer of safety, you can specify what D-Bus interface the proxy
+is expected to conform to by using the GDBusInterfaceInfo type.
+Additionally, GDBusProxy loads, caches and tracks changes to the D-Bus
+properties on the remote object. It also sets up match rules so D-Bus
+signals from the remote object are delivered locally.
+
+The GDBusProxy type normally isn't used directly - instead proxies
+subclassing GDBusProxy generated by `gdbus-codegen` is used, see the section
+called “Using gdbus-codegen”.
+
+## Generating code and docs
+
+### Using gdbus-codegen
+
+dbus-glib comes with dbus-binding-tool, which can produce somewhat nice
+client- and server-side wrappers for a D-Bus interface. With GDBus,
+gdbus-codegen is used and like its counterpart, it also takes D-Bus
+Introspection XML as input:
+
+#### Example D-Bus Introspection XML
+
+```xml
+<node>
+  <!-- org.gtk.GDBus.Example.ObjectManager.Animal:
+       @short_description: Example docs generated by gdbus-codegen
+       @since: 2.30
+
+       This D-Bus interface is used to describe a simple animal.
+    -->
+  <interface name="org.gtk.GDBus.Example.ObjectManager.Animal">
+    <!-- Mood: The mood of the animal.
+         @since: 2.30
+
+         Known values for this property include
+         <literal>Happy</literal> and <literal>Sad</literal>. Use the
+         org.gtk.GDBus.Example.ObjectManager.Animal.Poke() method to
+         change this property.
+
+         This property influences how often the animal jumps up and
+         down, see the
+         #org.gtk.GDBus.Example.ObjectManager.Animal::Jumped signal
+         for more details.
+    -->
+    <property name="Mood" type="s" access="read"/>
+
+    <!--
+        Poke:
+        @make_sad: Whether to make the animal sad.
+        @make_happy: Whether to make the animal happy.
+        @since: 2.30
+
+        Method used to changing the mood of the animal. See also the
+        #org.gtk.GDBus.Example.ObjectManager.Animal:Mood property.
+      -->
+    <method name="Poke">
+      <arg direction="in" type="b" name="make_sad"/>
+      <arg direction="in" type="b" name="make_happy"/>
+    </method>
+
+    <!--
+        Jumped:
+        @height: Height, in meters, that the animal jumped.
+        @since: 2.30
+
+        Emitted when the animal decides to jump.
+      -->
+    <signal name="Jumped">
+      <arg type="d" name="height"/>
+    </signal>
+
+    <!--
+        Foo:
+        Property with no <quote>since</quote> annotation (should inherit the 2.30 from its containing interface).
+      -->
+    <property name="Foo" type="s" access="read"/>
+
+    <!--
+        Bar:
+        @since: 2.36
+        Property with a later <quote>since</quote> annotation.
+      -->
+    <property name="Bar" type="s" access="read"/>
+  </interface>
+
+  <!-- org.gtk.GDBus.Example.ObjectManager.Cat:
+       @short_description: More example docs generated by gdbus-codegen
+
+       This D-Bus interface is used to describe a cat. Right now there
+       are no properties, methods or signals associated with this
+       interface so it is essentially a <ulink
+       url="http://en.wikipedia.org/wiki/Marker_interface_pattern">Marker
+       Interface</ulink>.
+
+       Note that D-Bus objects implementing this interface also
+       implement the #org.gtk.GDBus.Example.ObjectManager.Animal
+       interface.
+    -->
+  <interface name="org.gtk.GDBus.Example.ObjectManager.Cat">
+  </interface>
+</node>
+```
+
+If this XML is processed like this
+
+```
+gdbus-codegen --interface-prefix org.gtk.GDBus.Example.ObjectManager. \
+              --generate-c-code generated-code	                      \
+              --c-namespace Example 				      \
+              --c-generate-object-manager			      \
+              --generate-docbook generated-docs                       \
+              gdbus-example-objectmanager.xml
+```
+
+then two files generated-code.h and generated-code.c are generated.
+Additionally, two XML files
+generated-docs-org.gtk.GDBus.Example.ObjectManager.Animal and
+generated-docs-org.gtk.GDBus.Example.ObjectManager.Cat with Docbook XML are
+generated.
+
+While the contents of `generated-code.h` and `generated-code.c` are best described by the `gdbus-codegen` manual page, here's a brief example of how this generated code can be used:
+
+```c
+#include "gdbus-object-manager-example/objectmanager-gen.h"
+
+/* ---------------------------------------------------------------------------------------------------- */
+
+static GDBusObjectManagerServer *manager = NULL;
+
+static gboolean
+on_animal_poke (ExampleAnimal          *animal,
+                GDBusMethodInvocation  *invocation,
+                gboolean                make_sad,
+                gboolean                make_happy,
+                gpointer                user_data)
+{
+  if ((make_sad && make_happy) || (!make_sad && !make_happy))
+    {
+      g_dbus_method_invocation_return_dbus_error (invocation,
+                                                  "org.gtk.GDBus.Examples.ObjectManager.Error.Failed",
+                                                  "Exactly one of make_sad or make_happy must be TRUE");
+      goto out;
+    }
+
+  if (make_sad)
+    {
+      if (g_strcmp0 (example_animal_get_mood (animal), "Sad") == 0)
+        {
+          g_dbus_method_invocation_return_dbus_error (invocation,
+                                                      "org.gtk.GDBus.Examples.ObjectManager.Error.SadAnimalIsSad",
+                                                      "Sad animal is already sad");
+          goto out;
+        }
+
+      example_animal_set_mood (animal, "Sad");
+      example_animal_complete_poke (animal, invocation);
+      goto out;
+    }
+
+  if (make_happy)
+    {
+      if (g_strcmp0 (example_animal_get_mood (animal), "Happy") == 0)
+        {
+          g_dbus_method_invocation_return_dbus_error (invocation,
+                                                      "org.gtk.GDBus.Examples.ObjectManager.Error.HappyAnimalIsHappy",
+                                                      "Happy animal is already happy");
+          goto out;
+        }
+
+      example_animal_set_mood (animal, "Happy");
+      example_animal_complete_poke (animal, invocation);
+      goto out;
+    }
+
+  g_assert_not_reached ();
+
+ out:
+  return G_DBUS_METHOD_INVOCATION_HANDLED;
+}
+
+
+static void
+on_bus_acquired (GDBusConnection *connection,
+                 const gchar     *name,
+                 gpointer         user_data)
+{
+  ExampleObjectSkeleton *object;
+  guint n;
+
+  g_print ("Acquired a message bus connection\n");
+
+  /* Create a new org.freedesktop.DBus.ObjectManager rooted at /example/Animals */
+  manager = g_dbus_object_manager_server_new ("/example/Animals");
+
+  for (n = 0; n < 10; n++)
+    {
+      gchar *s;
+      ExampleAnimal *animal;
+
+      /* Create a new D-Bus object at the path /example/Animals/N where N is 000..009 */
+      s = g_strdup_printf ("/example/Animals/%03d", n);
+      object = example_object_skeleton_new (s);
+      g_free (s);
+
+      /* Make the newly created object export the interface
+       * org.gtk.GDBus.Example.ObjectManager.Animal (note
+       * that @object takes its own reference to @animal).
+       */
+      animal = example_animal_skeleton_new ();
+      example_animal_set_mood (animal, "Happy");
+      example_object_skeleton_set_animal (object, animal);
+      g_object_unref (animal);
+
+      /* Cats are odd animals - so some of our objects implement the
+       * org.gtk.GDBus.Example.ObjectManager.Cat interface in addition
+       * to the .Animal interface
+       */
+      if (n % 2 == 1)
+        {
+          ExampleCat *cat;
+          cat = example_cat_skeleton_new ();
+          example_object_skeleton_set_cat (object, cat);
+          g_object_unref (cat);
+        }
+
+      /* Handle Poke() D-Bus method invocations on the .Animal interface */
+      g_signal_connect (animal,
+                        "handle-poke",
+                        G_CALLBACK (on_animal_poke),
+                        NULL); /* user_data */
+
+      /* Export the object (@manager takes its own reference to @object) */
+      g_dbus_object_manager_server_export (manager, G_DBUS_OBJECT_SKELETON (object));
+      g_object_unref (object);
+    }
+
+  /* Export all objects */
+  g_dbus_object_manager_server_set_connection (manager, connection);
+}
+
+static void
+on_name_acquired (GDBusConnection *connection,
+                  const gchar     *name,
+                  gpointer         user_data)
+{
+  g_print ("Acquired the name %s\n", name);
+}
+
+static void
+on_name_lost (GDBusConnection *connection,
+              const gchar     *name,
+              gpointer         user_data)
+{
+  g_print ("Lost the name %s\n", name);
+}
+
+
+gint
+main (gint argc, gchar *argv[])
+{
+  GMainLoop *loop;
+  guint id;
+
+  loop = g_main_loop_new (NULL, FALSE);
+
+  id = g_bus_own_name (G_BUS_TYPE_SESSION,
+                       "org.gtk.GDBus.Examples.ObjectManager",
+                       G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT |
+                       G_BUS_NAME_OWNER_FLAGS_REPLACE,
+                       on_bus_acquired,
+                       on_name_acquired,
+                       on_name_lost,
+                       loop,
+                       NULL);
+
+  g_main_loop_run (loop);
+
+  g_bus_unown_name (id);
+  g_main_loop_unref (loop);
+
+  return 0;
+}
+```
+
+This, on the other hand, is a client-side application using generated code:
+
+```c
+#include "gdbus-object-manager-example/objectmanager-gen.h"
+
+/* ---------------------------------------------------------------------------------------------------- */
+
+static void
+print_objects (GDBusObjectManager *manager)
+{
+  GList *objects;
+  GList *l;
+
+  g_print ("Object manager at %s\n", g_dbus_object_manager_get_object_path (manager));
+  objects = g_dbus_object_manager_get_objects (manager);
+  for (l = objects; l != NULL; l = l->next)
+    {
+      ExampleObject *object = EXAMPLE_OBJECT (l->data);
+      GList *interfaces;
+      GList *ll;
+      g_print (" - Object at %s\n", g_dbus_object_get_object_path (G_DBUS_OBJECT (object)));
+
+      interfaces = g_dbus_object_get_interfaces (G_DBUS_OBJECT (object));
+      for (ll = interfaces; ll != NULL; ll = ll->next)
+        {
+          GDBusInterface *interface = G_DBUS_INTERFACE (ll->data);
+          g_print ("   - Interface %s\n", g_dbus_interface_get_info (interface)->name);
+
+          /* Note that @interface is really a GDBusProxy instance - and additionally also
+           * an ExampleAnimal or ExampleCat instance - either of these can be used to
+           * invoke methods on the remote object. For example, the generated function
+           *
+           *  void example_animal_call_poke_sync (ExampleAnimal  *proxy,
+           *                                      gboolean        make_sad,
+           *                                      gboolean        make_happy,
+           *                                      GCancellable   *cancellable,
+           *                                      GError        **error);
+           *
+           * can be used to call the Poke() D-Bus method on the .Animal interface.
+           * Additionally, the generated function
+           *
+           *  const gchar *example_animal_get_mood (ExampleAnimal *object);
+           *
+           * can be used to get the value of the :Mood property.
+           */
+        }
+      g_list_free_full (interfaces, g_object_unref);
+    }
+  g_list_free_full (objects, g_object_unref);
+}
+
+static void
+on_object_added (GDBusObjectManager *manager,
+                 GDBusObject        *object,
+                 gpointer            user_data)
+{
+  gchar *owner;
+  owner = g_dbus_object_manager_client_get_name_owner (G_DBUS_OBJECT_MANAGER_CLIENT (manager));
+  g_print ("Added object at %s (owner %s)\n", g_dbus_object_get_object_path (object), owner);
+  g_free (owner);
+}
+
+static void
+on_object_removed (GDBusObjectManager *manager,
+                   GDBusObject        *object,
+                   gpointer            user_data)
+{
+  gchar *owner;
+  owner = g_dbus_object_manager_client_get_name_owner (G_DBUS_OBJECT_MANAGER_CLIENT (manager));
+  g_print ("Removed object at %s (owner %s)\n", g_dbus_object_get_object_path (object), owner);
+  g_free (owner);
+}
+
+static void
+on_notify_name_owner (GObject    *object,
+                      GParamSpec *pspec,
+                      gpointer    user_data)
+{
+  GDBusObjectManagerClient *manager = G_DBUS_OBJECT_MANAGER_CLIENT (object);
+  gchar *name_owner;
+
+  name_owner = g_dbus_object_manager_client_get_name_owner (manager);
+  g_print ("name-owner: %s\n", name_owner);
+  g_free (name_owner);
+}
+
+static void
+on_interface_proxy_properties_changed (GDBusObjectManagerClient *manager,
+                                       GDBusObjectProxy         *object_proxy,
+                                       GDBusProxy               *interface_proxy,
+                                       GVariant                 *changed_properties,
+                                       const gchar *const       *invalidated_properties,
+                                       gpointer                  user_data)
+{
+  GVariantIter iter;
+  const gchar *key;
+  GVariant *value;
+  gchar *s;
+
+  g_print ("Properties Changed on %s:\n", g_dbus_object_get_object_path (G_DBUS_OBJECT (object_proxy)));
+  g_variant_iter_init (&iter, changed_properties);
+  while (g_variant_iter_next (&iter, "{&sv}", &key, &value))
+    {
+      s = g_variant_print (value, TRUE);
+      g_print ("  %s -> %s\n", key, s);
+      g_variant_unref (value);
+      g_free (s);
+    }
+}
+
+gint
+main (gint argc, gchar *argv[])
+{
+  GDBusObjectManager *manager;
+  GMainLoop *loop;
+  GError *error;
+  gchar *name_owner;
+
+  manager = NULL;
+  loop = NULL;
+
+  loop = g_main_loop_new (NULL, FALSE);
+
+  error = NULL;
+  manager = example_object_manager_client_new_for_bus_sync (G_BUS_TYPE_SESSION,
+                                                            G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_NONE,
+                                                            "org.gtk.GDBus.Examples.ObjectManager",
+                                                            "/example/Animals",
+                                                            NULL, /* GCancellable */
+                                                            &error);
+  if (manager == NULL)
+    {
+      g_printerr ("Error getting object manager client: %s", error->message);
+      g_error_free (error);
+      goto out;
+    }
+
+  name_owner = g_dbus_object_manager_client_get_name_owner (G_DBUS_OBJECT_MANAGER_CLIENT (manager));
+  g_print ("name-owner: %s\n", name_owner);
+  g_free (name_owner);
+
+  print_objects (manager);
+
+  g_signal_connect (manager,
+                    "notify::name-owner",
+                    G_CALLBACK (on_notify_name_owner),
+                    NULL);
+  g_signal_connect (manager,
+                    "object-added",
+                    G_CALLBACK (on_object_added),
+                    NULL);
+  g_signal_connect (manager,
+                    "object-removed",
+                    G_CALLBACK (on_object_removed),
+                    NULL);
+  g_signal_connect (manager,
+                    "interface-proxy-properties-changed",
+                    G_CALLBACK (on_interface_proxy_properties_changed),
+                    NULL);
+
+  g_main_loop_run (loop);
+
+ out:
+  if (manager != NULL)
+    g_object_unref (manager);
+  if (loop != NULL)
+    g_main_loop_unref (loop);
+
+  return 0;
+}
+```

docs/reference/gio/migrating-gdbus.xml

@@ -1,310 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-                  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
-<!ENTITY version SYSTEM "version.xml">
-]>
-<chapter>
-  <title>Migrating to GDBus</title>
-
-  <section>
-    <title>Conceptual differences</title>
-
-    <para>
-      The central concepts of D-Bus are modelled in a very similar way
-      in dbus-glib and GDBus. Both have objects representing connections,
-      proxies and method invocations. But there are some important
-      differences:
-      <itemizedlist>
-        <listitem><para>
-          dbus-glib uses the <ulink
-          url="http://www.freedesktop.org/wiki/Software/dbus#ReferenceImplementation.28dbus-daemonandlibdbus.29">libdbus
-          reference implementation</ulink>, GDBus doesn't. Instead, it
-          relies on GIO streams as transport layer, and has its own
-          implementation for the D-Bus connection setup and
-          authentication. Apart from using streams as transport,
-          avoiding libdbus also lets GDBus avoid some thorny
-          multithreading issues.
-        </para></listitem>
-        <listitem><para>
-          dbus-glib uses the GObject type system for method arguments and
-          return values, including a homegrown container specialization
-          mechanism. GDBus relies on the #GVariant type system which is
-          explicitly designed to match D-Bus types.
-        </para></listitem>
-        <listitem><para>
-          dbus-glib models only D-Bus interfaces and does not provide
-          any types for objects. GDBus models both D-Bus interfaces
-          (via the #GDBusInterface, #GDBusProxy and
-          #GDBusInterfaceSkeleton types) and objects (via the
-          #GDBusObject, #GDBusObjectSkeleton and #GDBusObjectProxy types).
-        </para></listitem>
-        <listitem><para>
-          GDBus includes native support for the <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties">org.freedesktop.DBus.Properties</ulink> (via the #GDBusProxy type) and <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">org.freedesktop.DBus.ObjectManager</ulink> D-Bus interfaces, dbus-glib doesn't.
-        </para></listitem>
-        <listitem><para>
-          The typical way to export an object in dbus-glib involves
-          generating glue code from XML introspection data using
-          <command>dbus-binding-tool</command>. GDBus provides a
-          similar tool called <command><link
-          linkend="gdbus-codegen">gdbus-codegen</link></command> that
-          can also generate Docbook D-Bus interface documentation.
-        </para></listitem>
-        <listitem><para>
-          dbus-glib doesn't provide any convenience API for owning and
-          watching bus names, GDBus provides the g_bus_own_name() and
-          g_bus_watch_name() family of convenience functions.
-        </para></listitem>
-        <listitem><para>
-          GDBus provides API to parse, generate and work with <link
-          linkend="gio-D-Bus-Introspection-Data">Introspection
-          XML</link>, dbus-glib doesn't.
-        </para></listitem>
-        <listitem><para>
-          GTestDBus provides API to create isolated unit tests <link
-          linkend="gio-D-Bus-Test-Scaffolding">GDBus Test Scaffolding</link>.
-        </para></listitem>
-      </itemizedlist>
-    </para>
-  </section>
-
-  <section>
-    <title>API comparison</title>
-
-    <table id="dbus-glib-vs-gdbus">
-      <title>dbus-glib APIs and their GDBus counterparts</title>
-      <tgroup cols="2">
-        <thead>
-           <row><entry>dbus-glib</entry><entry>GDBus</entry></row>
-        </thead>
-        <tbody>
-          <row><entry>#DBusGConnection</entry><entry>#GDBusConnection</entry></row>
-          <row><entry>#DBusGProxy</entry><entry>#GDBusProxy, #GDBusInterface - also see #GDBusObjectProxy</entry></row>
-          <row><entry>#DBusGObject</entry><entry>#GDBusInterfaceSkeleton, #GDBusInterface - also see #GDBusObjectSkeleton</entry></row>
-          <row><entry>#DBusGMethodInvocation</entry><entry>#GDBusMethodInvocation</entry></row>
-          <row><entry>dbus_g_bus_get()</entry><entry>g_bus_get_sync(), also see
-               g_bus_get()</entry></row>
-          <row><entry>dbus_g_proxy_new_for_name()</entry><entry>g_dbus_proxy_new_sync() and
-               g_dbus_proxy_new_for_bus_sync(), also see g_dbus_proxy_new()</entry></row>
-          <row><entry>dbus_g_proxy_add_signal()</entry><entry>not needed, use the generic #GDBusProxy::g-signal</entry></row>
-          <row><entry>dbus_g_proxy_connect_signal()</entry><entry>use g_signal_connect() with #GDBusProxy::g-signal</entry></row>
-          <row><entry>dbus_g_connection_register_g_object()</entry><entry>g_dbus_connection_register_object() - also see g_dbus_object_manager_server_export()</entry></row>
-          <row><entry>dbus_g_connection_unregister_g_object()</entry><entry>g_dbus_connection_unregister_object() - also see g_dbus_object_manager_server_unexport()</entry></row>
-          <row><entry>dbus_g_object_type_install_info()</entry><entry>introspection data is installed while registering
-               an object, see g_dbus_connection_register_object()</entry></row>
-          <row><entry>dbus_g_proxy_begin_call()</entry><entry>g_dbus_proxy_call()</entry></row>
-          <row><entry>dbus_g_proxy_end_call()</entry><entry>g_dbus_proxy_call_finish()</entry></row>
-          <row><entry>dbus_g_proxy_call()</entry><entry>g_dbus_proxy_call_sync()</entry></row>
-          <row><entry>dbus_g_error_domain_register()</entry><entry>g_dbus_error_register_error_domain()</entry></row>
-          <row><entry>dbus_g_error_has_name()</entry><entry>no direct equivalent, see g_dbus_error_get_remote_error()</entry></row>
-          <row><entry>dbus_g_method_return()</entry><entry>g_dbus_method_invocation_return_value()</entry></row>
-          <row><entry>dbus_g_method_return_error()</entry><entry>g_dbus_method_invocation_return_error() and variants</entry></row>
-          <row><entry>dbus_g_method_get_sender()</entry><entry>g_dbus_method_invocation_get_sender()</entry></row>
-        </tbody>
-      </tgroup>
-    </table>
-  </section>
-
-  <section>
-    <title>Owning bus names</title>
-    <para>
-      Using dbus-glib, you typically call RequestName manually
-      to own a name, like in the following excerpt:
-      <informalexample><programlisting><![CDATA[
-  error = NULL;
-  res = dbus_g_proxy_call (system_bus_proxy,
-                           "RequestName",
-                           &error,
-                           G_TYPE_STRING, NAME_TO_CLAIM,
-                           G_TYPE_UINT,   DBUS_NAME_FLAG_ALLOW_REPLACEMENT,
-                           G_TYPE_INVALID,
-                           G_TYPE_UINT,   &result,
-                           G_TYPE_INVALID);
-  if (!res)
-    {
-      if (error != NULL)
-        {
-          g_warning ("Failed to acquire %s: %s",
-                     NAME_TO_CLAIM, error->message);
-          g_error_free (error);
-        }
-      else
-        {
-          g_warning ("Failed to acquire %s", NAME_TO_CLAIM);
-        }
-      goto out;
-    }
-
-  if (result != DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER)
-    {
-      if (error != NULL)
-        {
-          g_warning ("Failed to acquire %s: %s",
-                     NAME_TO_CLAIM, error->message);
-          g_error_free (error);
-        }
-      else
-        {
-          g_warning ("Failed to acquire %s", NAME_TO_CLAIM);
-        }
-      exit (1);
-    }
-
-  dbus_g_proxy_add_signal (system_bus_proxy, "NameLost",
-                           G_TYPE_STRING, G_TYPE_INVALID);
-  dbus_g_proxy_connect_signal (system_bus_proxy, "NameLost",
-                               G_CALLBACK (on_name_lost), NULL, NULL);
-
-  /* further setup ... */
-]]>
-      </programlisting></informalexample>
-    </para>
-    <para>
-    While you can do things this way with GDBus too, using
-    g_dbus_proxy_call_sync(), it is much nicer to use the high-level API
-    for this:
-    <informalexample><programlisting><![CDATA[
-static void
-on_name_acquired (GDBusConnection *connection,
-                  const gchar     *name,
-                  gpointer         user_data)
-{
-  /* further setup ... */
-}
-
-/* ... */
-
-  owner_id = g_bus_own_name (G_BUS_TYPE_SYSTEM,
-                             NAME_TO_CLAIM,
-                             G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT,
-                             on_bus_acquired,
-                             on_name_acquired,
-                             on_name_lost,
-                             NULL,
-                             NULL);
-
-  g_main_loop_run (loop);
-
-  g_bus_unown_name (owner_id);
-]]>
-    </programlisting></informalexample>
-    Note that g_bus_own_name() works asynchronously and requires
-    you to enter your mainloop to await the on_name_aquired()
-    callback. Also note that in order to avoid race conditions (e.g.
-    when your service is activated by a method call), you have to export
-    your manager object <emphasis>before</emphasis> acquiring the
-    name. The on_bus_acquired() callback is the right place to do
-    such preparations.
-    </para>
-  </section>
-
-  <section>
-    <title>Creating proxies for well-known names</title>
-    <para>
-      dbus-glib lets you create proxy objects for well-known names, like the
-      following example:
-      <informalexample><programlisting><![CDATA[
-  proxy = dbus_g_proxy_new_for_name (system_bus_connection,
-                                     "org.freedesktop.Accounts",
-                                     "/org/freedesktop/Accounts",
-                                     "org.freedesktop.Accounts");
-      ]]>
-      </programlisting></informalexample>
-      For a #DBusGProxy constructed like this, method calls will be sent to
-      the current owner of the name, and that owner can change over time.
-    </para>
-    <para>
-      The same can be achieved with #GDBusProxy:
-      <informalexample><programlisting><![CDATA[
-  error = NULL;
-  proxy = g_dbus_proxy_new_for_bus_sync (G_BUS_TYPE_SYSTEM,
-                                         G_DBUS_PROXY_FLAGS_NONE,
-                                         NULL, /* GDBusInterfaceInfo */
-                                         "org.freedesktop.Accounts",
-                                         "/org/freedesktop/Accounts",
-                                         "org.freedesktop.Accounts",
-                                         NULL, /* GCancellable */
-                                         &error);
-      ]]>
-      </programlisting></informalexample>
-      For an added layer of safety, you can specify what D-Bus
-      interface the proxy is expected to conform to by using the
-      #GDBusInterfaceInfo type.  Additionally, #GDBusProxy loads,
-      caches and tracks changes to the D-Bus properties on the remote
-      object. It also sets up match rules so D-Bus signals from the
-      remote object are delivered locally.
-    </para>
-    <para>
-      The #GDBusProxy type normally isn't used directly - instead
-      proxies subclassing #GDBusProxy generated by <command><link
-      linkend="gdbus-codegen">gdbus-codegen</link></command> is used, see <xref linkend="gdbus-example-gdbus-codegen"/>
-    </para>
-  </section>
-
-  <section>
-    <title>Generating code and docs</title>
-
-  <section id="gdbus-example-gdbus-codegen">
-    <title>Using gdbus-codegen</title>
-
-    <para>
-      dbus-glib comes with <command>dbus-binding-tool</command>, which
-      can produce somewhat nice client- and server-side wrappers for a D-Bus interface.
-      With GDBus, <command><link
-      linkend="gdbus-codegen">gdbus-codegen</link></command> is used and like
-      its counterpart, it also takes D-Bus Introspection XML as input:
-    </para>
-    <example id="gdbus-example-codegen-input"><title>Example D-Bus Introspection XML</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../../gio/tests/gdbus-object-manager-example/gdbus-example-objectmanager.xml"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT: gdbus-example-objectmanager.xml</xi:fallback></xi:include></programlisting></example>
-    <para>
-      If this XML is processed like this
-<informalexample><programlisting><![CDATA[
-gdbus-codegen --interface-prefix org.gtk.GDBus.Example.ObjectManager. \
-              --generate-c-code generated-code	                      \
-              --c-namespace Example 				      \
-              --c-generate-object-manager			      \
-              --generate-docbook generated-docs                       \
-              gdbus-example-objectmanager.xml
-]]></programlisting></informalexample>
-      then two files <filename>generated-code.h</filename> and
-      <filename>generated-code.c</filename> are
-      generated. Additionally, two XML files
-      <filename>generated-docs-org.gtk.GDBus.Example.ObjectManager.Animal</filename> and
-      <filename>generated-docs-org.gtk.GDBus.Example.ObjectManager.Cat</filename>
-      with Docbook XML are generated. For an example of what the docs look
-      like see <link
-      linkend="gdbus-interface-org-gtk-GDBus-Example-ObjectManager-Animal">the Animal D-Bus interface documentation</link>.
-      and
-      <link
-      linkend="gdbus-interface-org-gtk-GDBus-Example-ObjectManager-Cat">the Cat D-Bus interface documentation</link>.
-    </para>
-    <para>
-      While the contents of <filename>generated-code.h</filename> and
-      <filename>generated-code.c</filename> are best described by the
-      <command><link
-      linkend="gdbus-codegen">gdbus-codegen</link></command> manual
-      page, brief examples of how this generated code can be used can be found in
-      <xref linkend="gdbus-example-codegen-server"/>
-      and <xref
-      linkend="gdbus-example-codegen-client"/>. Additionally, since
-      the generated code has 100% gtk-doc coverage, see
-      #ExampleAnimal, #ExampleCat, #ExampleObject and
-      #ExampleObjectManagerClient pages for documentation.
-    </para>
-
-    <example id="gdbus-example-codegen-server"><title>Server-side application using generated code</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../../gio/tests/gdbus-example-objectmanager-server.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT: gdbus-example-objectmanager-server.c</xi:fallback></xi:include></programlisting></example>
-
-    <example id="gdbus-example-codegen-client"><title>Client-side application using generated code</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../../gio/tests/gdbus-example-objectmanager-client.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT: gdbus-example-objectmanager-client.c</xi:fallback></xi:include></programlisting></example>
-
-  </section>
-
-  <!-- All XInclude paths are relative to the html/ directory under the build root directory -->
-  <xi:include href="../../../../gio/tests/gdbus-object-manager-example/objectmanager-gen-org.gtk.GDBus.Example.ObjectManager.Animal.xml"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT: objectmanager-gen-org.gtk.GDBus.Example.ObjectManager.Animal.xml</xi:fallback></xi:include>
-  <xi:include href="../../../../gio/tests/gdbus-object-manager-example/objectmanager-gen-org.gtk.GDBus.Example.ObjectManager.Cat.xml"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT: objectmanager-gen-org.gtk.GDBus.Example.ObjectManager.Cat.xml</xi:fallback></xi:include>
-  <xi:include href="../gdbus-object-manager-example/xml/ExampleAnimal.xml"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT: ExampleAnimal.xml</xi:fallback></xi:include>
-  <xi:include href="../gdbus-object-manager-example/xml/ExampleCat.xml"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT: ExampleCat.xml</xi:fallback></xi:include>
-  <xi:include href="../gdbus-object-manager-example/xml/ExampleObject.xml"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT: ExampleObject.xml</xi:fallback></xi:include>
-  <xi:include href="../gdbus-object-manager-example/xml/ExampleObjectManagerClient.xml"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT: ExampleObjectManagerClient.xml</xi:fallback></xi:include>
-
-  </section>
-
-</chapter>

docs/reference/gio/migrating-gnome-vfs.md

@@ -0,0 +1,109 @@
+Title: Migrating from GnomeVFS to GIO
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 2010 Matthias Clasen
+
+# Migrating from GnomeVFS to GIO
+
+## Comparison of GnomeVFS and GIO concepts
+
+| GnomeVFS | GIO |
+|----------|-----|
+| `GnomeVFSURI` | [iface@Gio.File] |
+| `GnomeVFSFileInfo` | [class@Gio.FileInfo] |
+| `GnomeVFSResult` | [struct@GLib.Error], with `G_IO_ERROR` values |
+| `GnomeVFSHandle` & `GnomeVFSAsyncHandle` | [class@Gio.InputStream] or [class@Gio.OutputStream] |
+| `GnomeVFSDirectoryHandle` | [class@Gio.FileEnumerator] |
+| MIME type | content type |
+| `GnomeVFSMonitor` | [class@Gio.FileMonitor] |
+| `GnomeVFSVolumeMonitor` | [class@Gio.VolumeMonitor] |
+| `GnomeVFSVolume` | [iface@Gio.Mount] |
+| `GnomeVFSDrive` | [iface@Gio.Volume] |
+| - | [iface@Gio.Drive] |
+| `GnomeVFSContext` | [class@Gio.Cancellable] |
+| `gnome_vfs_async_cancel()` | [method@Gio.Cancellable.cancel] |
+
+## Trash handling
+
+The handling of trashed files has been changed in GIO, compared to
+gnome-vfs. gnome-vfs has a home-grown trash implementation that predates the
+freedesktop.org [Desktop Trash
+Can](http://www.freedesktop.org/wiki/Specifications/trash-spec)
+specification that is implemented in GIO.  The location for storing trashed
+files has changed from `$HOME/.Trash` to `$HOME/.local/share/Trash` (or more
+correctly `$XDG_DATA_HOME/Trash`), which means that there is a need for
+migrating files that have been trashed by gnome-vfs to the new location.
+
+In gnome-vfs, the `trash://` scheme offering a merged view of all trash
+directories was implemented in Nautilus, and trash-handling applications had
+to find and monitor all trash directories themselves. With GIO, the
+`trash://` implementation has been moved to gvfs and applications can simply
+monitor that location:
+
+```c
+static void
+file_changed (GFileMonitor      *file_monitor,
+              GFile             *child,
+              GFile             *other_file,
+              GFileMonitorEvent  event_type,
+              gpointer           user_data)
+{
+  switch (event_type)
+  {
+  case G_FILE_MONITOR_EVENT_DELETED:
+    g_print ("'%s' removed from trash\n", g_file_get_basename (child));
+    break;
+  case G_FILE_MONITOR_EVENT_CREATED:
+    g_print ("'%s' added to trash\n", g_file_get_basename (child));
+    break;
+  default: ;
+  }
+}
+
+static void
+start_monitoring_trash (void)
+{
+  GFile *file;
+  GFileMonitor *monitor;
+
+  file = g_file_new_for_uri ("trash://");
+  monitor = g_file_monitor_directory (file, 0, NULL, NULL);
+  g_object_unref (file);
+
+  g_signal_connect (monitor, "changed", G_CALLBACK (file_changed), NULL);
+
+  /* ... */
+
+}
+```
+
+GIO exposes some useful metadata about trashed files. There are
+`trash::orig-path` and `trash::deletion-date` attributes. The
+`standard::icon` attribute of the `trash://` itself provides a suitable icon
+for displaying the trash can on the desktop. If you are using this icon,
+make sure to monitor this attribute for changes, since the icon may be
+updated to reflect that state of the trash can.
+
+Moving a file to the trash is much simpler with GIO. Instead of using
+`gnome_vfs_find_directory()` with `GNOME_VFS_DIRECTORY_KIND_TRASH` to find
+out where to move the trashed file, just use the [`method@Gio.File.trash`]
+method.
+
+## Operations on multiple files
+
+gnome-vfs has the dreaded `gnome_vfs_xfer_uri_list()` function which has
+tons of options and offers the equivalent of `cp`, `mv`, `ln`, `mkdir` and
+`rm` at the same time.
+
+GIO offers a much simpler asynchronous task functionality instead, that lets
+you schedule a function to be called in a separate thread, making sure that
+updates are scheduled within the main context that created the task, so you
+can update your user interface. See: [`class@Gio.Task`].
+
+## Mime monitoring
+
+gnome-vfs offered a way to monitor the association between mime types and
+default handlers for changes, with the `GnomeVFSMIMEMonitor` object. GIO
+does not offer a replacement for this functionality at this time, since we
+have not found a compelling use case where `GnomeVFSMIMEMonitor` was used.
+If you think you have such a use case, please [open an issue on the GLib
+issue tracker](https://gitlab.gnome.org/GNOME/glib/issues/new).

docs/reference/gio/migrating-gnome-vfs.xml

@@ -1,133 +0,0 @@
-  <chapter>
-    <title>Migrating from GnomeVFS to GIO</title>
-
-    <table id="gnome-vfs-vs-gio">
-      <title>Comparison of GnomeVFS and GIO concepts</title>
-      <tgroup cols="2">
-        <thead>
-          <row><entry>GnomeVFS</entry><entry>GIO</entry></row>
-        </thead>
-        <tbody>
-          <row><entry>GnomeVFSURI</entry><entry>GFile</entry></row>
-          <row><entry>GnomeVFSFileInfo</entry><entry>GFileInfo</entry></row>
-          <row><entry>GnomeVFSResult</entry><entry>GError, with G_IO_ERROR values</entry></row>
-          <row><entry>GnomeVFSHandle &amp; GnomeVFSAsyncHandle</entry><entry>GInputStream or GOutputStream</entry></row>
-          <row><entry>GnomeVFSDirectoryHandle</entry><entry>GFileEnumerator</entry></row>
-          <row><entry>mime type</entry><entry>content type</entry></row>
-          <row><entry>GnomeVFSMonitor</entry><entry>GFileMonitor</entry></row>
-          <row><entry>GnomeVFSVolumeMonitor</entry><entry>GVolumeMonitor</entry></row>
-          <row><entry>GnomeVFSVolume</entry><entry>GMount</entry></row>
-          <row><entry>GnomeVFSDrive</entry><entry>GVolume</entry></row>
-          <row><entry>-</entry><entry>GDrive</entry></row>
-          <row><entry>GnomeVFSContext</entry><entry>GCancellable</entry></row>
-          <row><entry>gnome_vfs_async_cancel</entry><entry>g_cancellable_cancel</entry></row>
-        </tbody>
-      </tgroup>
-    </table>
-
-    <section>
-      <title>Trash handling</title>
-
-      <para>
-        The handling of trashed files has been changed in GIO, compared
-        to gnome-vfs. gnome-vfs has a home-grown trash implementation that 
-        predates the freedesktop.org <ulink url="http://www.freedesktop.org/wiki/Specifications/trash-spec">Desktop Trash Can</ulink> specification
-        that is implemented in GIO. The location for storing trashed files 
-        has changed from <filename>$HOME/.Trash</filename> to 
-        <filename>$HOME/.local/share/Trash</filename> (or more correctly
-        <filename>$XDG_DATA_HOME/Trash</filename>), which means that 
-        there is a need for migrating files that have been trashed by 
-        gnome-vfs to the new location.
-      </para>
-      <para>
-        In gnome-vfs, the <filename>trash://</filename> scheme offering a 
-        merged view of all trash directories was implemented in nautilus,
-        and trash-handling applications had to find and monitor all trash 
-        directories themselves. With GIO, the <filename>trash://</filename>
-        implementation has been moved to gvfs and applications can simply
-        monitor that location:
-      </para>
-<informalexample><programlisting>
-static void
-file_changed (GFileMonitor      *file_monitor,
-              GFile             *child,
-              GFile             *other_file,
-              GFileMonitorEvent  event_type,
-              gpointer           user_data)
-{
-  switch (event_type)
-  {
-  case G_FILE_MONITOR_EVENT_DELETED:
-    g_print ("'%s' removed from trash\n", g_file_get_basename (child));
-    break;
-  case G_FILE_MONITOR_EVENT_CREATED:
-    g_print ("'%s' added to trash\n", g_file_get_basename (child));
-    break;
-  default: ;
-  }
-}
-
-static void
-start_monitoring_trash (void)
-{
-  GFile *file;
-  GFileMonitor *monitor;
-
-  file = g_file_new_for_uri ("trash://");
-  monitor = g_file_monitor_directory (file, 0, NULL, NULL);
-  g_object_unref (file);
-
-  g_signal_connect (monitor, "changed", G_CALLBACK (file_changed), NULL);
-
-  /* ... */
-
-}       
-</programlisting></informalexample> 
-      <para>
-        GIO exposes some useful metadata about trashed files. There are
-        trash::orig-path and trash::deletion-date attributes. The 
-        standard::icon attribute of the <filename>trash://</filename> 
-        itself provides a suitable icon for displaying the trash can on 
-        the desktop. If you are using this icon, make sure to monitor
-        this attribute for changes, since the icon may be updated to
-        reflect that state of the trash can.
-      </para>
-      <para>
-        Moving a file to the trash is much simpler with GIO. Instead of
-        using gnome_vfs_find_directory() with %GNOME_VFS_DIRECTORY_KIND_TRASH 
-        to find out where to move the trashed file, just use the g_file_trash()
-        function.
-      </para>
-    </section>
-
-    <section>
-      <title>Operations on multiple files</title>
-
-      <para>
-        gnome-vfs has the dreaded gnome_vfs_xfer_uri_list() function which
-        has tons of options and offers the equivalent of cp, mv, ln, mkdir
-        and rm at the same time. 
-      </para>
-      <para>
-        GIO offers a much simpler I/O scheduler functionality instead, that
-        lets you schedule a function to be called in a separate thread, or
-        if threads are not available, as an idle in the mainloop.
-        See g_io_scheduler_push_job(). 
-      </para>
-
-    </section>
-
-    <section>
-      <title>Mime monitoring</title>
-
-      <para>
-        gnome-vfs offered a way to monitor the association between mime types
-        and default handlers for changes, with the #GnomeVFSMIMEMonitor object.
-        GIO does not offer a replacement for this functionality at this time,
-        since we have not found a compelling use case where
-        #GnomeVFSMIMEMonitor was used. If you think you have such a use
-        case, please report it at
-        <ulink url="https://gitlab.gnome.org/GNOME/glib/issues/new">https://gitlab.gnome.org/GNOME/glib/issues/new</ulink>.
-      </para>
-    </section>
-  </chapter>

docs/reference/gio/migrating-posix.md

@@ -0,0 +1,21 @@
+Title: Migrating from POSIX to GIO
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 2007 Matthias Clasen
+
+# Migrating from POSIX to GIO
+
+## Comparison of POSIX and GIO concepts
+
+The final two entries in this table require including `gio-unix-2.0.pc` as well
+as `gio-2.0.pc` in your build (or, in GIR namespace terms, `GioUnix-2.0` as well
+as `Gio-2.0`).
+
+| POSIX                 | GIO                                                         |
+|-----------------------|-------------------------------------------------------------|
+| `char *path`          | [iface@Gio.File]                                            |
+| `struct stat *buf`    | [class@Gio.FileInfo]                                        |
+| `struct statvfs *buf` | [class@Gio.FileInfo]                                        |
+| `int fd`              | [class@Gio.InputStream] or [class@Gio.OutputStream]         |
+| `DIR *`               | [class@Gio.FileEnumerator]                                  |
+| `fstab entry`         | [`GUnixMountPoint`](../gio-unix/struct.UnixMountPoint.html) |
+| `mtab entry`          | [`GUnixMountEntry`](../gio-unix/struct.UnixMountEntry.html) |

docs/reference/gio/migrating-posix.xml

@@ -1,27 +0,0 @@
-<part id="migrating">
-  <title>Migrating to GIO</title>
-
-  <chapter>
-    <title>Migrating from POSIX to GIO</title>
-  
-    <table id="posix-vs-gio">
-      <title>Comparison of POSIX and GIO concepts</title>
-      <tgroup cols="2">
-        <thead>
-          <row><entry>POSIX</entry><entry>GIO</entry></row>
-        </thead>
-        <tbody>
-          <row><entry>char *path</entry><entry>GFile *file</entry></row>
-          <row><entry>struct stat *buf</entry><entry>GFileInfo *info</entry></row>
-          <row><entry>struct statvfs *buf</entry><entry>GFileInfo *info</entry></row>
-          <row><entry morerows="1">int fd</entry><entry>GInputStream *in</entry></row>
-          <row><entry>GOutputStream *out</entry></row>
-          <row><entry>DIR *</entry><entry>GFileEnumerator *enum</entry></row>
-          <row><entry>fstab entry</entry><entry>GUnixMountPoint *mount_point</entry></row>
-          <row><entry>mtab entry</entry><entry>GUnixMountEntry *mount_entry</entry></row>
-        </tbody>
-      </tgroup>
-    </table>  
-
-  </chapter>
-</part>

docs/reference/gio/networking.md

@@ -0,0 +1,29 @@
+Title: gnetworking.h
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 2010 Dan Winship
+
+# gnetworking.h
+
+The `<gio/gnetworking.h>` header can be included to get
+various low-level networking-related system headers, automatically
+taking care of certain portability issues for you.
+
+This can be used, for example, if you want to call
+[`setsockopt()`](man:setsockopt(2)) on a [class@Gio.Socket].
+
+Note that while WinSock has many of the same APIs as the
+traditional UNIX socket API, most of them behave at least slightly
+differently (particularly with respect to error handling). If you
+want your code to work under both UNIX and Windows, you will need
+to take these differences into account.
+
+Also, under GNU libc, certain non-portable functions are only visible
+in the headers if you define `_GNU_SOURCE` before including them. Note
+that this symbol must be defined before including any headers, or it
+may not take effect.
+
+There is one function provided specifically for initialising the networking
+APIs, which needs to be called only if they are being used before GLib
+initialises itself:
+
+ * [func@Gio.networking_init]

docs/reference/gio/overview.md

@@ -0,0 +1,406 @@
+Title: Overview
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 2007, 2008, 2010, 2011, 2012, 2013 Matthias Clasen
+SPDX-FileCopyrightText: 2007, 2009 Alexander Larsson
+SPDX-FileCopyrightText: 2008 A. Walton
+SPDX-FileCopyrightText: 2010 David Zeuthen
+SPDX-FileCopyrightText: 2013 Stef Walter
+SPDX-FileCopyrightText: 2015 Collabora, Ltd.
+SPDX-FileCopyrightText: 2016 Colin Walters
+SPDX-FileCopyrightText: 2020 Wouter Bolsterlee
+SPDX-FileCopyrightText: 2022 Endless OS Foundation, LLC
+
+# Overview
+
+GIO is striving to provide a modern, easy-to-use VFS API that sits at the
+right level in the library stack, as well as other generally useful APIs
+for desktop applications (such as networking and D-Bus support). The goal
+is to overcome the shortcomings of GnomeVFS and provide an API that is so
+good that developers prefer it over raw POSIX calls. Among other things
+that means using GObject. It also means not cloning the POSIX API, but
+providing higher-level, document-centric interfaces.
+
+The abstract file system model of GIO consists of a number of interfaces and
+base classes for I/O and files:
+
+[iface@Gio.File]
+: reference to a file
+
+[class@Gio.FileInfo]
+: information about a file or filesystem
+
+[class@Gio.FileEnumerator]
+: list files in directories
+
+[iface@Gio.Drive]
+: represents a drive
+
+[iface@Gio.Volume]
+: represents a file system in an abstract way
+
+[iface@Gio.Mount]
+: represents a mounted file system
+
+Then there is a number of stream classes, similar to the input and output
+stream hierarchies that can be found in frameworks like Java:
+
+[class@Gio.InputStream]
+: read data
+
+[class@Gio.OutputStream]
+: write data
+
+[class@Gio.IOStream]
+: read and write data
+
+[iface@Gio.Seekable]
+: interface optionally implemented by streams to support seeking
+
+There are interfaces related to applications and the types of files they
+handle:
+
+[iface@Gio.AppInfo]
+: information about an installed application
+
+[iface@Gio.Icon]
+: abstract type for file and application icons
+
+There is a framework for storing and retrieving application settings:
+
+[class@Gio.Settings]
+: stores and retrieves application settings
+
+There is support for network programming, including connectivity monitoring,
+name resolution, lowlevel socket APIs and highlevel client and server helper
+classes:
+
+[class@Gio.Socket]
+: lowlevel platform independent socket object
+
+[class@Gio.Resolver]
+: asynchronous and cancellable DNS resolver
+
+[class@Gio.SocketClient]
+: high-level network client helper
+
+[class@Gio.SocketService]
+: high-level network server helper
+
+[class@Gio.SocketConnection]
+: network connection stream
+
+[iface@Gio.NetworkMonitor]
+: network connectivity monitoring
+
+There is support for connecting to
+[D-Bus](https://www.freedesktop.org/wiki/Software/dbus/), sending and receiving
+messages, owning and watching bus names, and making objects available on the bus:
+
+[class@Gio.DBusConnection]
+: a D-Bus connection
+
+[class@Gio.DBusMethodInvocation]
+: for handling remote calls
+
+[class@Gio.DBusServer]
+: helper for accepting connections
+
+[class@Gio.DBusProxy]
+: proxy to access D-Bus interfaces on a remote object
+
+Beyond these, GIO provides facilities for file monitoring, asynchronous I/O
+and filename completion. In addition to the interfaces, GIO provides
+implementations for the local case. Implementations for various network file
+systems are provided by the GVFS package as loadable modules.
+
+Other design choices which consciously break with the GnomeVFS design are to
+move backends out-of-process, which minimizes the dependency bloat and makes
+the whole system more robust. The backends are not included in GIO, but in
+the separate GVFS package. The GVFS package also contains the GVFS daemon,
+which spawn further mount daemons for each individual connection.
+
+![GIO in the GTK library stack](./gvfs-overview.png)
+
+The GIO model of I/O is stateful: if an application establishes e.g. a SFTP
+connection to a server, it becomes available to all applications in the
+session; the user does not have to enter his password over and over again.
+
+One of the big advantages of putting the VFS in the GLib layer is that GTK
+can directly use it, e.g. in the filechooser.
+
+## Writing GIO applications
+
+The information in the GLib documentation about writing GLib applications is
+generally applicable when writing GIO applications.
+
+### Threads
+
+GDBus has its own private worker thread, so applications using GDBus have at
+least 3 threads. GIO makes heavy use of the concept of a thread-default main
+context to execute callbacks of asynchronous methods in the same context in
+which the operation was started.
+
+### Asynchronous Programming
+
+Many GIO functions come in two versions: synchronous and asynchronous,
+denoted by an `_async` suffix. It is important to use these appropriately:
+synchronous calls should not be used from within a main loop which is shared
+with other code, such as one in the application’s main thread. Synchronous
+calls block until they complete, and I/O operations can take noticeable
+amounts of time (even on ‘fast’ SSDs). Blocking a main loop iteration while
+waiting for I/O means that other sources in the main loop will not be
+dispatched, such as input and redraw handlers for the application’s UI. This
+can cause the application to ‘freeze’ until I/O completes.
+
+A few self-contained groups of functions, such as code generated by
+gdbus-codegen, use a different convention: functions are asynchronous
+default, and it is the synchronous version which has a `_sync` suffix. Aside
+from naming differences, they should be treated the same way as functions
+following the normal convention above.
+
+The asynchronous (`_async`) versions of functions return control to the
+caller immediately, after scheduling the I/O in the kernel and adding a
+callback for it to the main loop. This callback will be invoked when the
+operation has completed. From the callback, the paired `_finish` function
+should be called to retrieve the return value of the I/O operation, and any
+errors which occurred. For more information on using and implementing
+asynchronous functions, see [iface@Gio.AsyncResult] and [class@Gio.Task].
+
+By starting multiple asynchronous operations in succession, they will be
+executed in parallel (up to an arbitrary limit imposed by GIO’s internal
+worker thread pool).
+
+The synchronous versions of functions can be used early in application
+startup when there is no main loop to block, for example to load initial
+configuration files. They can also be used for I/O on files which are
+guaranteed to be small and on the local disk. Note that the user’s home
+directory is not guaranteed to be on the local disk.  Security
+
+When your program needs to carry out some privileged operation (say, create
+a new user account), there are various ways in which you can go about this:
+
+- Implement a daemon that offers the privileged operation. A convenient way
+  to do this is as a D-Bus system-bus service. The daemon will probably need
+  ways to check the identity and authorization of the caller before
+  executing the operation.
+  [polkit](https://www.freedesktop.org/software/polkit/docs/latest/polkit.8.html)
+  is a framework that allows this.
+- Use a small helper that is executed with elevated privileges via pkexec.
+  [`pkexec`](https://www.freedesktop.org/software/polkit/docs/latest/pkexec.1.html)
+  is a small program launcher that is part of polkit.
+- Use a small helper that is executed with elevated privileges by being suid
+  root.
+
+None of these approaches is the clear winner, they all have their advantages
+and disadvantages.
+
+When writing code that runs with elevated privileges, it is important to
+follow some basic rules of secure programming. David Wheeler has an
+excellent book on this topic,
+[Secure Programming for Linux and Unix HOWTO](https://dwheeler.com/secure-programs/Secure-Programs-HOWTO/index.html).
+
+When using GIO in code that runs with elevated privileges, you have to be
+careful. GIO has extension points whose implementations get loaded from
+modules (executable code in shared objects), which could allow an attacker
+to sneak his own code into your application by tricking it into loading the
+code as a module. However, GIO will never load modules from your home
+directory except when explicitly asked to do so via an environment variable.
+
+In most cases, your helper program should be so small that you don't need
+GIO, whose APIs are largely designed to support full-blown desktop
+applications. If you can't resist the convenience of these APIs, here are
+some steps you should take:
+
+- Clear the environment, e.g. using the `clearenv()` function. David Wheeler
+  has a good
+  [explanation](https://dwheeler.com/secure-programs/Secure-Programs-HOWTO/environment-variables.html)
+  for why it is important to sanitize the environment. See the section on
+  running GIO applications for a list of all environment variables affecting
+  GIO. In particular, `PATH` (used to locate binaries), `GIO_EXTRA_MODULES`
+  (used to locate loadable modules) and `DBUS_{SYSTEM,SESSION}_BUS_ADDRESS`
+  (used to locate the D-Bus system and session bus) are important.
+- Don't use GVfs, by setting `GIO_USE_VFS=local` in the environment. The
+  reason to avoid GVfs in security-sensitive programs is that it uses many
+  libraries which have not necessarily been audited for security problems.
+  Gvfs is also heavily distributed and relies on a session bus to be
+  present.
+
+## Compiling GIO applications
+
+GIO comes with a `gio-2.0.pc` file that you should use together with
+pkg-config to obtain the necessary information about header files and
+libraries. See the pkg-config man page or the GLib documentation for more
+information on how to use pkg-config to compile your application.
+
+If you are using GIO on UNIX-like systems, you may want to use UNIX-specific
+GIO interfaces such as `GUnixInputStream`, `GUnixOutputStream`, `GUnixMount`
+or `GDesktopAppInfo`. To do so, use the `gio-unix-2.0.pc` file as well as
+`gio-2.0.pc` (or, in GIR namespace terms, `GioUnix-2.0` as well as `Gio-2.0`).
+
+## Running GIO applications
+
+GIO inspects a few environment variables in addition to the ones used by GLib.
+
+- `XDG_DATA_HOME`, `XDG_DATA_DIRS`.  GIO uses these environment variables to
+  locate MIME information. For more information, see the
+  [Shared MIME-info Database](https://specifications.freedesktop.org/shared-mime-info-spec/latest/)
+  and the [Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/latest/).
+- `GVFS_DISABLE_FUSE`.  This variable can be set to keep Gvfs from starting
+  the fuse backend, which may be unwanted or unnecessary in certain
+  situations.
+- `GIO_USE_VFS`.  This environment variable can be set to the name of a GVfs
+  implementation to override the default for debugging purposes. The GVfs
+  implementation for local files that is included in GIO has the name
+  "local", the implementation in the gvfs module has the name "gvfs". Most
+  commonly, system software will set this to "local" to avoid having `GFile`
+  APIs perform unnecessary D-Bus calls. The special value help can be used
+  to print a list of available implementations to standard output.
+
+The following environment variables are only useful for debugging GIO itself
+or modules that it loads. They should not be set in a production
+environment.
+
+- `GIO_USE_FILE_MONITOR`.  This variable can be set to the name of a
+  GFileMonitor implementation to override the default for debugging
+  purposes. The GFileMonitor implementation for local files that is included
+  in GIO on Linux has the name "inotify", others that are built are built as
+  modules (depending on the platform) are called "fam" and "fen". The
+  special value help can be used to print a list of available
+  implementations to standard output.
+- `GIO_USE_VOLUME_MONITOR`.  This variable can be set to the name of a
+  GVolumeMonitor implementation to override the default for debugging
+  purposes. The GVolumeMonitor implementation for local files that is
+  included in GIO has the name "unix", the udisks2-based implementation in
+  the gvfs module has the name "udisks2". The special value help can be used
+  to print a list of available implementations to standard output.
+- `GIO_USE_TLS`.  This variable can be set to the name of a GTlsBackend
+  implementation to override the default for debugging purposes. GIO does
+  not include a GTlsBackend implementation, the gnutls-based implementation
+  in the glib-networking module has the name "gnutls". The special value
+  help can be used to print a list of available implementations to standard
+  output.
+- `GIO_USE_PORTALS`.  This variable can be set to override detection of portals
+  and force them to be used to provide various bits of GIO functionality, for
+  testing and debugging. This variable is not intended to be used in production.
+- `GIO_MODULE_DIR`.  When this environment variable is set to a path, GIO
+  will load modules from this alternate directory instead of the directory
+  built into GIO. This is useful when running tests, for example. This
+  environment variable is ignored when running in a setuid program.
+- `GIO_EXTRA_MODULES`.  When this environment variable is set to a path, or
+  a set of paths separated by a colon, GIO will attempt to load additional
+  modules from within the path. This environment variable is ignored when
+  running in a setuid program.
+- `GSETTINGS_BACKEND`.  This variable can be set to the name of a
+  GSettingsBackend implementation to override the default for debugging
+  purposes. The memory-based implementation that is included in GIO has the
+  name "memory", the one in dconf has the name "dconf". The special value
+  help can be used to print a list of available implementations to standard
+  output.
+- `GSETTINGS_SCHEMA_DIR`.  This variable can be set to the names of
+  directories to consider when looking for compiled schemas for GSettings,
+  in addition to the `glib-2.0/schemas` subdirectories of the XDG system
+  data dirs. To specify multiple directories, use `G_SEARCHPATH_SEPARATOR_S`
+  as a separator.
+- `DBUS_SYSTEM_BUS_ADDRESS`.  This variable is consulted to find the address
+  of the D-Bus system bus. For the format of D-Bus addresses, see the
+  [D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
+  Setting this variable overrides platform-specific ways of determining the
+  system bus address.
+- `DBUS_SESSION_BUS_ADDRESS`.  This variable is consulted to find the
+  address of the D-Bus session bus. Setting this variable overrides
+  platform-specific ways of determining the session bus address.
+- `DBUS_STARTER_BUS_TYPE`.  This variable is consulted to find out the
+  'starter' bus for an application that has been started via D-Bus
+  activation. The possible values are 'system' or 'session'.
+- `G_DBUS_DEBUG`.  This variable can be set to a list of debug options,
+  which cause GLib to print out different types of debugging information
+  when using the D-Bus routines.
+  - `transport`: Show IO activity (e.g. reads and writes)
+  - `message`: Show all sent and received D-Bus messages
+  - `payload`: Show payload for all sent and received D-Bus messages (implies
+    message)
+  - `call`: Trace `g_dbus_connection_call()` and
+    `g_dbus_connection_call_sync()` API usage
+  - `signal`: Show when a D-Bus signal is received
+  - `incoming`: Show when an incoming D-Bus method call is received
+  - `return`: Show when a reply is returned via the GDBusMethodInvocation API
+  - `emission`: Trace `g_dbus_connection_emit_signal()` API usage
+  - `authentication`: Show information about connection authentication
+  - `address`: Show information about D-Bus address lookups and autolaunching
+  - `all`: Turn on all debug options
+  - `help`: Print a list of supported options to the standard output
+- `G_DBUS_COOKIE_SHA1_KEYRING_DIR`.  Can be used to override the directory
+  used to store the keyring used in the `DBUS_COOKIE_SHA1` authentication
+  mechanism. Normally the directory used is `.dbus-keyrings` in the user's
+  home directory.
+- `G_DBUS_COOKIE_SHA1_KEYRING_DIR_IGNORE_PERMISSION`.  If set, the
+  permissions of the directory used to store the keyring used in the
+  `DBUS_COOKIE_SHA1` authentication mechanism won't be checked. Normally the
+  directory must be readable only by the user.
+
+## Extending GIO
+
+A lot of the functionality that is accessible through GIO is implemented in
+loadable modules, and modules provide a convenient way to extend GIO. In
+addition to the [`class@Gio.IOModule`] API which supports writing such modules, GIO has a
+mechanism to define extension points, and register implementations thereof,
+see [`struct@Gio.IOExtensionPoint`].
+
+The following extension points are currently defined by GIO:
+
+- `G_VFS_EXTENSION_POINT_NAME`.  Allows to override the functionality of the
+  GVfs class. Implementations of this extension point must be derived from
+  GVfs. GIO uses the implementation with the highest priority that is
+  active, see `g_vfs_is_active()`. GIO implements this extension point for
+  local files, gvfs contains an implementation that supports all the
+  backends in gvfs.
+- `G_VOLUME_MONITOR_EXTENSION_POINT_NAME`.  Allows to add more volume
+  monitors. Implementations of this extension point must be derived from
+  GVolumeMonitor. GIO uses all registered extensions. gvfs contains an
+  implementation that works together with the GVfs implementation in gvfs.
+- `G_NATIVE_VOLUME_MONITOR_EXTENSION_POINT_NAME`.  Allows to override the
+  'native' volume monitor. Implementations of this extension point must be
+  derived from GNativeVolumeMonitor. GIO uses the implementation with the
+  highest priority that is supported, as determined by the `is_supported()`
+  vfunc in GVolumeMonitorClass. GIO implements this extension point for
+  local mounts, gvfs contains a udisks2-based implementation.
+- `G_LOCAL_FILE_MONITOR_EXTENSION_POINT_NAME`.  Allows to override the file
+  monitor implementation for local files. Implementations of this extension
+  point must be derived from GLocalFileMonitor. GIO uses the implementation
+  with the highest priority that is supported, as determined by the
+  `is_supported()` vfunc in GLocalFileMonitorClass. GIO uses this extension
+  point internally, to switch between its fam-based and inotify-based file
+  monitoring implementations.
+- `G_LOCAL_DIRECTORY_MONITOR_EXTENSION_POINT_NAME`.  Allows to override the
+  directory monitor implementation for local files. Implementations of this
+  extension point must be derived from GLocalDirectoryMonitor. GIO uses the
+  implementation with the highest priority that is supported, as determined
+  by the `is_supported()` vfunc in GLocalDirectoryMonitorClass. GIO uses
+  this extension point internally, to switch between its fam-based and
+  inotify-based directory monitoring implementations.
+- `G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME`.  Unix-only. Allows to
+  provide a way to associate default handlers with URI schemes.
+  Implementations of this extension point must implement the
+  GDesktopAppInfoLookup interface. GIO uses the implementation with the
+  highest priority. This extension point has been discontinued in GLib 2.28.
+  It is still available to keep API and ABI stability, but GIO is no longer
+  using it for default handlers. Instead, the mime handler mechanism is
+  used, together with x-scheme-handler pseudo-mimetypes.
+- `G_SETTINGS_BACKEND_EXTENSION_POINT_NAME`.  Allows to provide an
+  alternative storage for GSettings. Implementations of this extension point
+  must derive from the GSettingsBackend type. GIO contains a keyfile-based
+  implementation of this extension point, another one is provided by dconf.
+- `G_PROXY_EXTENSION_POINT_NAME`.  Allows to provide implementations for
+  network proxying. Implementations of this extension point must provide the
+  GProxy interface, and must be named after the network protocol they are
+  proxying. glib-networking contains an implementation of this extension
+  point based on libproxy.
+- `G_TLS_BACKEND_EXTENSION_POINT_NAME`.  Allows to provide implementations
+  for TLS support. Implementations of this extension point must implement
+  the GTlsBackend interface. glib-networking contains an implementation of
+  this extension point.
+- `G_NETWORK_MONITOR_EXTENSION_POINT_NAME`.  Allows to provide
+  implementations for network connectivity monitoring. Implementations of
+  this extension point must implement the GNetworkMonitorInterface
+  interface. GIO contains an implementation of this extension point that is
+  using the netlink interface of the Linux kernel.

docs/reference/gio/overview.xml

@@ -1,745 +0,0 @@
-<part>
-  <title>GIO Overview</title>
-
-  <chapter>
-    <title>Introduction</title>
-
-  <para>
-    GIO is striving to provide a modern, easy-to-use VFS API that sits
-    at the right level in the library stack, as well as other generally
-    useful APIs for desktop applications (such as networking and
-    D-Bus support). The goal is to overcome the shortcomings of GnomeVFS
-    and provide an API that is so good that developers prefer it over raw
-    POSIX calls. Among other things that means using GObject. It also means
-    not cloning the POSIX API, but providing higher-level, document-centric
-    interfaces.
-  </para>
-
-  <para>
-    The abstract file system model of GIO consists of a number of
-    interfaces and base classes for I/O and files:
-    <variablelist>
-       <varlistentry>
-         <term>GFile</term>
-         <listitem><para>reference to a file</para></listitem>
-       </varlistentry>
-       <varlistentry>
-         <term>GFileInfo</term>
-         <listitem><para>information about a file or filesystem</para></listitem>
-       </varlistentry>
-       <varlistentry>
-         <term>GFileEnumerator</term>
-         <listitem><para>list files in directories</para></listitem>
-       </varlistentry>
-       <varlistentry>
-         <term>GDrive</term>
-         <listitem><para>represents a drive</para></listitem>
-       </varlistentry>
-       <varlistentry>
-         <term>GVolume</term>
-         <listitem><para>represents a file system in an abstract way</para></listitem>
-       </varlistentry>
-       <varlistentry>
-         <term>GMount</term>
-         <listitem><para>represents a mounted file system</para></listitem>
-       </varlistentry>
-    </variablelist>
-    Then there is a number of stream classes, similar to the input and
-    output stream hierarchies that can be found in frameworks like Java:
-    <variablelist>
-       <varlistentry>
-         <term>GInputStream</term>
-         <listitem><para>read data</para></listitem>
-       </varlistentry>
-       <varlistentry>
-         <term>GOutputStream</term>
-         <listitem><para>write data</para></listitem>
-       </varlistentry>
-       <varlistentry>
-         <term>GIOStream</term>
-         <listitem><para>read and write data</para></listitem>
-       </varlistentry>
-       <varlistentry>
-         <term>GSeekable</term>
-         <listitem><para>interface optionally implemented by streams to support seeking</para></listitem>
-       </varlistentry>
-    </variablelist>
-    There are interfaces related to applications and the types
-    of files they handle:
-    <variablelist>
-       <varlistentry>
-          <term>GAppInfo</term>
-          <listitem><para>information about an installed application</para></listitem>
-       </varlistentry>
-       <varlistentry>
-          <term>GIcon</term>
-          <listitem><para>abstract type for file and application icons</para></listitem>
-       </varlistentry>
-    </variablelist>
-    There is a framework for storing and retrieving application settings:
-    <variablelist>
-       <varlistentry>
-          <term>GSettings</term>
-          <listitem><para>stores and retrieves application settings</para></listitem>
-       </varlistentry>
-    </variablelist>
-    There is support for network programming, including connectivity monitoring,
-    name resolution, lowlevel socket APIs and highlevel client and server
-    helper classes:
-    <variablelist>
-       <varlistentry>
-          <term>GSocket</term>
-          <listitem><para>lowlevel platform independent socket object</para></listitem>
-       </varlistentry>
-       <varlistentry>
-          <term>GResolver</term>
-          <listitem><para>asynchronous and cancellable DNS resolver</para></listitem>
-       </varlistentry>
-       <varlistentry>
-          <term>GSocketClient</term>
-          <listitem><para>high-level network client helper</para></listitem>
-       </varlistentry>
-       <varlistentry>
-          <term>GSocketService</term>
-          <listitem><para>high-level network server helper</para></listitem>
-       </varlistentry>
-       <varlistentry>
-          <term>GSocketConnection</term>
-          <listitem><para>network connection stream</para></listitem>
-       </varlistentry>
-       <varlistentry>
-          <term>GNetworkMonitor</term>
-          <listitem><para>network connectivity monitoring</para></listitem>
-       </varlistentry>
-    </variablelist>
-    There is support for connecting to <ulink url="http://www.freedesktop.org/wiki/Software/dbus">D-Bus</ulink>,
-    sending and receiving messages, owning and watching bus names,
-    and making objects available on the bus:
-    <variablelist>
-       <varlistentry>
-          <term>GDBusConnection</term>
-          <listitem><para>a D-Bus connection</para></listitem>
-       </varlistentry>
-
-       <varlistentry>
-          <term>GDBusMethodInvocation</term>
-          <listitem><para>for handling remote calls</para></listitem>
-       </varlistentry>
-
-       <varlistentry>
-          <term>GDBusServer</term>
-          <listitem><para>helper for accepting connections</para></listitem>
-       </varlistentry>
-
-       <varlistentry>
-          <term>GDBusProxy</term>
-          <listitem><para>proxy to access D-Bus interfaces on a remote object</para></listitem>
-       </varlistentry>
-
-    </variablelist>
-    Beyond these, GIO provides facilities for file monitoring,
-    asynchronous I/O and filename completion. In addition to the
-    interfaces, GIO provides implementations for the local case.
-    Implementations for various network file systems are provided
-    by the GVFS package as loadable modules.
-  </para>
-
-  <para>
-    Other design choices which consciously break with the GnomeVFS
-    design are to move backends out-of-process, which minimizes the
-    dependency bloat and makes the whole system more robust. The backends
-    are not included in GIO, but in the separate GVFS package. The GVFS
-    package also contains the GVFS daemon, which spawn further mount
-    daemons for each individual connection.
-  </para>
-
-  <figure id="gvfs-overview">
-    <title>GIO in the GTK library stack</title>
-    <graphic fileref="gvfs-overview.png" format="PNG"></graphic>
-  </figure>
-
-  <para>
-    The GIO model of I/O is stateful: if an application establishes e.g.
-    a SFTP connection to a server, it becomes available to all applications
-    in the session; the user does not have to enter their password over
-    and over again.
-  </para>
-  <para>
-    One of the big advantages of putting the VFS in the GLib layer
-    is that GTK can directly use it, e.g. in the filechooser.
-  </para>
-  </chapter>
-
-  <chapter>
-    <title>Writing GIO applications</title>
-
-    <para>
-      The information in the GLib <ulink url="http://developer.gnome.org/glib/stable/glib-programming.html">documentation</ulink> about writing GLib
-      applications is generally applicable when writing GIO applications.
-    </para>
-
-    <simplesect><title>Threads</title>
-
-    <para>
-       GDBus has its own private worker thread, so applications using
-       GDBus have at least 3 threads. GIO makes heavy use of the concept
-       of a <link linkend="g-main-context-push-thread-default">thread-default
-       main context</link> to execute callbacks of asynchronous
-       methods in the same context in which the operation was started.
-    </para>
-
-    </simplesect>
-
-    <simplesect id="async-programming"><title>Asynchronous Programming</title>
-
-    <para>
-      Many GIO functions come in two versions: synchronous and asynchronous,
-      denoted by an <code>_async</code> suffix. It is important to use these
-      appropriately: synchronous calls should not be used from
-      within a main loop which is shared with other code, such as one in the
-      application’s main thread. Synchronous calls block until they complete,
-      and I/O operations can take noticeable amounts of time (even on ‘fast’
-      SSDs). Blocking a main loop iteration while waiting for I/O means that
-      other sources in the main loop will not be dispatched, such as input and
-      redraw handlers for the application’s UI. This can cause the application
-      to ‘freeze’ until I/O completes.
-    </para>
-
-    <para>
-      A few self-contained groups of functions, such as code generated by
-      <link linkend="gdbus-codegen"><application>gdbus-codegen</application></link>,
-      use a different convention: functions are asynchronous default, and it is
-      the <emphasis>synchronous</emphasis> version which has a
-      <code>_sync</code>
-      suffix. Aside from naming differences, they should be treated the same
-      way as functions following the normal convention above.
-    </para>
-
-    <para>
-      The asynchronous (<code>_async</code>) versions of functions return
-      control to the caller immediately, after scheduling the I/O in the kernel
-      and adding a callback for it to the main loop. This callback will be
-      invoked when the operation has completed. From the callback, the paired
-      <code>_finish</code> function should be called to retrieve the return
-      value of the I/O operation, and any errors which occurred. For more
-      information on using and implementing asynchronous functions, see
-      <link linkend="GAsyncResult.description"><type>GAsyncResult</type></link>
-      and <link linkend="GTask.description"><type>GTask</type></link>.
-    </para>
-
-    <para>
-      By starting multiple asynchronous operations in succession, they will be
-      executed in parallel (up to an arbitrary limit imposed by GIO’s internal
-      worker thread pool).
-    </para>
-
-    <para>
-      The synchronous versions of functions can be used early in application
-      startup when there is no main loop to block, for example to load initial
-      configuration files. They can also be used for I/O on files which are
-      guaranteed to be small and on the local disk. Note that the user’s home
-      directory is not guaranteed to be on the local disk.
-    </para>
-    </simplesect>
-
-    <simplesect><title>Security</title>
-
-<para>
-When your program needs to carry out some privileged operation (say,
-create a new user account), there are various ways in which you can go
-about this:
-<itemizedlist>
-<listitem><para>
-Implement a daemon that offers the privileged operation. A convenient
-way to do this is as a D-Bus system-bus service. The daemon will probably
-need ways to check the identity and authorization of the caller before
-executing the operation. <ulink url="http://www.freedesktop.org/software/polkit/docs/latest/polkit.8.html">polkit</ulink> is a framework that allows this.
-</para></listitem>
-<listitem><para>
-Use a small helper that is executed with elevated privileges via
-pkexec. <ulink url="http://www.freedesktop.org/software/polkit/docs/latest/pkexec.1.html">pkexec</ulink> is a small program launcher that is part of polkit.
-</para></listitem>
-<listitem><para>
-Use a small helper that is executed with elevated privileges by
-being suid root.
-</para></listitem>
-</itemizedlist>
-None of these approaches is the clear winner, they all have their
-advantages and disadvantages.
-</para>
-
-<para>
-When writing code that runs with elevated privileges, it is important
-to follow some basic rules of secure programming. David Wheeler has an
-excellent book on this topic,
-<ulink url="http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/index.html">Secure Programming for Linux and Unix HOWTO</ulink>.
-</para>
-
-<para>
-When using GIO in code that runs with elevated privileges, you have to
-be careful. GIO has extension points whose implementations get loaded
-from modules (executable code in shared objects), which could allow
-an attacker to sneak their own code into your application by tricking it
-into loading the code as a module. However, GIO will never load modules
-from your home directory except when explicitly asked to do so via an
-environment variable.
-</para>
-
-<para>
-In most cases, your helper program should be so small that you don't
-need GIO, whose APIs are largely designed to support full-blown desktop
-applications. If you can't resist the convenience of these APIs, here
-are some steps you should take:
-<itemizedlist>
-<listitem><para>
-Clear the environment, e.g. using the <function>clearenv()</function>
-function.
-David Wheeler has a good <ulink url="http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/environment-variables.html">explanation</ulink> for why it is
-important to sanitize the environment.
-See <xref linkend="running-gio-apps"/>
-for a list of all environment variables affecting GIO. In particular,
-<envar>PATH</envar> (used to locate binaries), <envar>GIO_EXTRA_MODULES</envar> (used to locate loadable modules) and <envar>DBUS_{SYSTEM,SESSION}_BUS_ADDRESS</envar> (used to locate the D-Bus system and session bus) are important.
-</para></listitem>
-<listitem><para>
-Don't use GVfs, by setting <envar>GIO_USE_VFS=local</envar> in the environment.
-The reason to avoid GVfs in security-sensitive programs is that it uses
-many libraries which have not necessarily been audited for security problems.
-Gvfs is also heavily distributed and relies on a session bus to be present.
-</para></listitem>
-</itemizedlist>
-</para>
-
-    </simplesect>
-
-  </chapter>
-
-  <chapter>
-    <title>Compiling GIO applications</title>
-
-    <para>
-      GIO comes with a <filename>gio-2.0.pc</filename> file that you
-      should use together with <literal>pkg-config</literal> to obtain
-      the necessary information about header files and libraries. See
-      the <literal>pkg-config</literal> man page or the GLib documentation
-      for more information on how to use <literal>pkg-config</literal>
-      to compile your application.
-    </para>
-
-    <para>
-      If you are using GIO on UNIX-like systems, you may want to use
-      UNIX-specific GIO interfaces such as #GUnixInputStream,
-      #GUnixOutputStream, #GUnixMount or #GDesktopAppInfo.
-      To do so, use the <filename>gio-unix-2.0.pc</filename> file
-      instead of <filename>gio-2.0.pc</filename>
-    </para>
-  </chapter>
-
-  <chapter id="running-gio-apps">
-    <title>Running GIO applications</title>
-
-    <para>
-      GIO inspects a few environment variables in addition to the
-      ones used by GLib.
-    </para>
-
-    <formalpara>
-      <title><envar>XDG_DATA_HOME</envar>, <envar>XDG_DATA_DIRS</envar></title>
-
-      <para>
-        GIO uses these environment variables to locate MIME information.
-        For more information, see the <ulink url="http://freedesktop.org/Standards/shared-mime-info-spec">Shared MIME-info Database</ulink>
-        and the <ulink url="http://freedesktop.org/Standards/basedir-spec">Base Directory Specification</ulink>.
-      </para>
-    </formalpara>
-
-    <formalpara>
-      <title><envar>GVFS_DISABLE_FUSE</envar></title>
-
-      <para>
-        This variable can be set to keep #Gvfs from starting the fuse backend,
-        which may be unwanted or unnecessary in certain situations.
-      </para>
-    </formalpara>
-
-    <formalpara>
-      <title><envar>GIO_USE_VFS</envar></title>
-
-      <para>
-        This environment variable can be set to the name of a #GVfs
-        implementation to override the default for debugging purposes.
-        The #GVfs implementation for local files that is included in GIO
-        has the name "local", the implementation in the gvfs module has
-        the name "gvfs".  Most commonly, system software will set this to "local"
-        to avoid having `GFile` APIs perform unnecessary D-Bus calls.
-      </para><para>
-        The special value <literal>help</literal> can be used to print a list of
-        available implementations to standard output.
-      </para>
-    </formalpara>
-
-    <para>
-      The following environment variables are only useful for debugging
-      GIO itself or modules that it loads. They should not be set in a
-      production environment.
-    </para>
-
-    <formalpara>
-      <title><envar>GIO_USE_FILE_MONITOR</envar></title>
-
-      <para>
-        This variable can be set to the name of a #GFileMonitor
-        implementation to override the default for debugging purposes.
-        The #GFileMonitor implementation for local files that is included
-        in GIO on Linux has the name <literal>inotify</literal>, others that are built
-        are built as modules (depending on the platform) are called
-        <literal>kqueue</literal> and <literal>win32filemonitor</literal>.
-      </para><para>
-        The special value <literal>help</literal> can be used to print a list of
-        available implementations to standard output.
-      </para>
-    </formalpara>
-
-    <formalpara>
-      <title><envar>GIO_USE_VOLUME_MONITOR</envar></title>
-
-      <para>
-        This variable can be set to the name of a #GVolumeMonitor
-        implementation to override the default for debugging purposes.
-        The #GVolumeMonitor implementation for local files that is included
-        in GIO has the name "unix", the udisks2-based implementation in the
-        gvfs module has the name "udisks2".
-      </para><para>
-        The special value <literal>help</literal> can be used to print a list of
-        available implementations to standard output.
-      </para>
-    </formalpara>
-
-    <formalpara>
-      <title><envar>GIO_USE_TLS</envar></title>
-
-      <para>
-        This variable can be set to the name of a #GTlsBackend
-        implementation to override the default for debugging purposes.
-        GIO does not include a #GTlsBackend implementation, the gnutls-based
-        implementation in the glib-networking module has the name "gnutls".
-      </para><para>
-        The special value <literal>help</literal> can be used to print a list of
-        available implementations to standard output.
-      </para>
-    </formalpara>
-
-    <formalpara>
-      <title><envar>GIO_MODULE_DIR</envar></title>
-
-      <para>
-        When this environment variable is set to a path, GIO will load
-	modules from this alternate directory instead of the directory
-	built into GIO. This is useful when running tests, for example.
-      </para>
-      <para>
-        This environment variable is ignored when running in a setuid program.
-      </para>
-    </formalpara>
-
-    <formalpara>
-      <title><envar>GIO_EXTRA_MODULES</envar></title>
-
-      <para>
-        When this environment variable is set to a path, or a set of
-        paths separated by a colon, GIO will attempt to load
-        additional modules from within the path.
-      </para>
-      <para>
-        This environment variable is ignored when running in a setuid program.
-      </para>
-    </formalpara>
-
-    <formalpara>
-      <title><envar>GSETTINGS_BACKEND</envar></title>
-
-      <para>
-        This variable can be set to the name of a #GSettingsBackend
-        implementation to override the default for debugging purposes.
-        The memory-based implementation that is included in GIO has
-        the name "memory", the one in dconf has the name "dconf".
-      </para><para>
-        The special value <literal>help</literal> can be used to print a list of
-        available implementations to standard output.
-      </para>
-    </formalpara>
-
-    <formalpara>
-      <title><envar>GSETTINGS_SCHEMA_DIR</envar></title>
-
-      <para>
-        This variable can be set to the names of directories to consider when looking for compiled schemas for #GSettings,
-        in addition to the <filename>glib-2.0/schemas</filename>
-        subdirectories of the XDG system data dirs. To specify multiple directories, use <constant>G_SEARCHPATH_SEPARATOR_S</constant> as a separator.
-      </para>
-    </formalpara>
-
-   <formalpara>
-      <title><envar>DBUS_SYSTEM_BUS_ADDRESS</envar></title>
-
-      <para>
-        This variable is consulted to find the address of the D-Bus system
-        bus. For the format of D-Bus addresses, see the D-Bus
-        <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#addresses">specification</ulink>.
-      </para>
-      <para>
-        Setting this variable overrides platform-specific ways of determining
-        the system bus address.
-      </para>
-   </formalpara>
-
-   <formalpara>
-      <title><envar>DBUS_SESSION_BUS_ADDRESS</envar></title>
-
-      <para>
-        This variable is consulted to find the address of the D-Bus session bus.
-      </para>
-      <para>
-        Setting this variable overrides platform-specific ways of determining
-        the session bus address.
-      </para>
-   </formalpara>
-
-   <formalpara>
-      <title><envar>DBUS_STARTER_BUS_TYPE</envar></title>
-
-      <para>
-        This variable is consulted to find out the 'starter' bus for an
-        application that has been started via D-Bus activation. The possible
-        values are 'system' or 'session'.
-      </para>
-   </formalpara>
-
-   <formalpara>
-      <title><envar>G_DBUS_DEBUG</envar></title>
-
-      <para>
-         This variable can be set to a list of debug options, which
-         cause GLib to print out different types of debugging
-         information when using the D-Bus routines.
-         <variablelist>
-           <varlistentry>
-             <term>transport</term>
-             <listitem><para>Show IO activity (e.g. reads and writes)</para></listitem>
-           </varlistentry>
-           <varlistentry>
-             <term>message</term>
-             <listitem><para>Show all sent and received D-Bus messages</para></listitem>
-           </varlistentry>
-           <varlistentry>
-             <term>payload</term>
-             <listitem><para>Show payload for all sent and received D-Bus messages (implies message)</para></listitem>
-           </varlistentry>
-           <varlistentry>
-             <term>call</term>
-             <listitem><para>Trace g_dbus_connection_call() and g_dbus_connection_call_sync() API usage</para></listitem>
-           </varlistentry>
-           <varlistentry>
-             <term>signal</term>
-             <listitem><para>Show when a D-Bus signal is received</para></listitem>
-           </varlistentry>
-           <varlistentry>
-             <term>incoming</term>
-             <listitem><para>Show when an incoming D-Bus method call is received</para></listitem>
-           </varlistentry>
-           <varlistentry>
-             <term>return</term>
-             <listitem><para>Show when a reply is returned via the #GDBusMethodInvocation API</para></listitem>
-           </varlistentry>
-           <varlistentry>
-             <term>emission</term>
-             <listitem><para>Trace g_dbus_connection_emit_signal() API usage</para></listitem>
-           </varlistentry>
-           <varlistentry>
-             <term>authentication</term>
-             <listitem><para>Show information about connection authentication</para></listitem>
-           </varlistentry>
-           <varlistentry>
-             <term>address</term>
-             <listitem><para>Show information about D-Bus address lookups and autolaunching</para></listitem>
-           </varlistentry>
-         </variablelist>
-         The special value <literal>all</literal> can be used to turn
-         on all debug options. The special value
-         <literal>help</literal> can be used to print a list of
-         supported options to standard output.
-      </para>
-   </formalpara>
-
-   <formalpara>
-      <title><envar>G_DBUS_COOKIE_SHA1_KEYRING_DIR</envar></title>
-
-      <para>
-        Can be used to override the directory used to store the
-        keyring used in the <literal>DBUS_COOKIE_SHA1</literal>
-        authentication mechanism. Normally the directory used is
-        <filename>.dbus-keyrings</filename> in the user's home
-        directory.
-      </para>
-   </formalpara>
-
-   <formalpara>
-      <title><envar>G_DBUS_COOKIE_SHA1_KEYRING_DIR_IGNORE_PERMISSION</envar></title>
-
-      <para>
-        If set, the permissions of the directory used to store the
-        keyring used in the <literal>DBUS_COOKIE_SHA1</literal>
-        authentication mechanism won't be checked. Normally the
-        directory must be readable only by the user.
-      </para>
-   </formalpara>
-  </chapter>
-
-  <chapter id="extending-gio">
-    <title>Extending GIO</title>
-
-    <para>
-      A lot of the functionality that is accessible through GIO
-      is implemented in loadable modules, and modules provide a convenient
-      way to extend GIO. In addition to the #GIOModule API which supports
-      writing such modules, GIO has a mechanism to define extension points,
-      and register implementations thereof, see #GIOExtensionPoint.
-    </para>
-    <para>
-      The following extension points are currently defined by GIO:
-    </para>
-
-    <formalpara>
-       <title>G_VFS_EXTENSION_POINT_NAME</title>
-
-       <para>
-          Allows to override the functionality of the #GVfs class.
-          Implementations of this extension point must be derived from #GVfs.
-          GIO uses the implementation with the highest priority that is active,
-          see g_vfs_is_active().
-       </para>
-       <para>
-          GIO implements this extension point for local files, gvfs contains
-          an implementation that supports all the backends in gvfs.
-       </para>
-   </formalpara>
-
-   <formalpara>
-      <title>G_VOLUME_MONITOR_EXTENSION_POINT_NAME</title>
-
-      <para>
-         Allows to add more volume monitors.
-         Implementations of this extension point must be derived from
-         #GVolumeMonitor. GIO uses all registered extensions.
-      </para>
-      <para>
-        gvfs contains an implementation that works together with the #GVfs
-        implementation in gvfs.
-      </para>
-   </formalpara>
-
-   <formalpara>
-      <title>G_NATIVE_VOLUME_MONITOR_EXTENSION_POINT_NAME</title>
-
-      <para>
-         Allows to override the 'native' volume monitor.
-         Implementations of this extension point must be derived from
-         #GNativeVolumeMonitor. GIO uses the implementation with
-         the highest priority that is supported, as determined by the
-         is_supported() vfunc in #GVolumeMonitorClass.
-      </para>
-      <para>
-         GIO implements this extension point for local mounts,
-         gvfs contains a udisks2-based implementation.
-      </para>
-   </formalpara>
-
-   <formalpara>
-      <title>G_LOCAL_FILE_MONITOR_EXTENSION_POINT_NAME</title>
-
-      <para>
-        Allows to override the file monitor implementation for
-        local files. Implementations of this extension point must
-        be derived from #GLocalFileMonitor. GIO uses the implementation
-        with the highest priority that is supported, as determined by the
-        is_supported() vfunc in #GLocalFileMonitorClass.
-      </para>
-      <para>
-        GIO uses this extension point internally, to switch between
-        its kqueue-based and inotify-based file monitoring implementations.
-      </para>
-   </formalpara>
-
-   <formalpara>
-      <title>G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME</title>
-
-      <para>
-        Unix-only. Allows to provide a way to associate default handlers
-        with URI schemes. Implementations of this extension point must
-        implement the #GDesktopAppInfoLookup interface. GIO uses the
-        implementation with the highest priority.
-      </para>
-      <para>
-        This extension point has been discontinued in GLib 2.28. It is
-        still available to keep API and ABI stability, but GIO is no
-        longer using it for default handlers. Instead, the mime handler
-        mechanism is used, together with x-scheme-handler pseudo-mimetypes.
-      </para>
-   </formalpara>
-
-   <formalpara>
-      <title>G_SETTINGS_BACKEND_EXTENSION_POINT_NAME</title>
-
-      <para>
-        Allows to provide an alternative storage for #GSettings.
-        Implementations of this extension point must derive from the
-        #GSettingsBackend type. GIO contains a keyfile-based
-        implementation of this extension point, another one is provided
-        by dconf.
-      </para>
-   </formalpara>
-
-   <formalpara>
-     <title>G_PROXY_EXTENSION_POINT_NAME</title>
-
-     <para>
-       Allows to provide implementations for network proxying.
-       Implementations of this extension point must provide the
-       #GProxy interface, and must be named after the network
-       protocol they are proxying.
-     </para>
-     <para>
-       glib-networking contains an implementation of this extension
-       point based on libproxy.
-     </para>
-   </formalpara>
-   <formalpara>
-     <title>G_TLS_BACKEND_EXTENSION_POINT_NAME</title>
-
-     <para>
-       Allows to provide implementations for TLS support.
-       Implementations of this extension point must implement
-       the #GTlsBackend interface.
-     </para>
-     <para>
-       glib-networking contains an implementation of this extension
-       point.
-     </para>
-   </formalpara>
-
-   <formalpara>
-     <title>G_NETWORK_MONITOR_EXTENSION_POINT_NAME</title>
-
-     <para>
-       Allows to provide implementations for network connectivity
-       monitoring.
-       Implementations of this extension point must implement
-       the #GNetworkMonitorInterface interface.
-     </para>
-     <para>
-       GIO contains an implementation of this extension point
-       that is using the netlink interface of the Linux kernel.
-     </para>
-   </formalpara>
-  </chapter>
-</part>
-

docs/reference/gio/pollable-utils.md

@@ -0,0 +1,15 @@
+Title: Pollable Utility Functions
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 2012 Dan Winship
+
+# Pollable Utility Functions
+
+Utility functions for [iface@Gio.PollableInputStream] and
+[iface@Gio.PollableOutputStream] implementations.
+
+ * [func@Gio.pollable_source_new]
+ * [func@Gio.pollable_source_new_full]
+ * [func@Gio.pollable_stream_read]
+ * [func@Gio.pollable_stream_write]
+ * [func@Gio.pollable_stream_write_all]
+

docs/reference/gio/tls-overview.md

@@ -0,0 +1,37 @@
+Title: TLS Overview
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 2010 Dan Winship
+SPDX-FileCopyrightText: 2015 Collabora, Ltd.
+
+# TLS Overview
+
+[class@Gio.TlsConnection] and related classes provide TLS (Transport Layer
+Security, previously known as SSL, Secure Sockets Layer) support for GIO-based
+network streams.
+
+[iface@Gio.DtlsConnection] and related classes provide DTLS (Datagram TLS)
+support for GIO-based network sockets, using the [iface@Gio.DatagramBased]
+interface. The TLS and DTLS APIs are almost identical, except TLS is
+stream-based and DTLS is datagram-based. They share certificate and backend
+infrastructure.
+
+In the simplest case, for a client TLS connection, you can just set the
+[property@Gio.SocketClient:tls] flag on a [class@Gio.SocketClient], and then any
+connections created by that client will have TLS negotiated automatically, using
+appropriate default settings, and rejecting any invalid or self-signed
+certificates (unless you change that default by setting the
+[property@Gio.SocketClient:tls-validation-flags] property). The returned object
+will be a [class@Gio.TcpWrapperConnection], which wraps the underlying
+[iface@Gio.TlsClientConnection].
+
+For greater control, you can create your own [iface@Gio.TlsClientConnection],
+wrapping a [class@Gio.SocketConnection] (or an arbitrary [class@Gio.IOStream]
+with pollable input and output streams) and then connect to its signals,
+such as [signal@Gio.TlsConnection::accept-certificate], before starting the
+handshake.
+
+Server-side TLS is similar, using [iface@Gio.TlsServerConnection]. At the
+moment, there is no support for automatically wrapping server-side
+connections in the way [class@Gio.SocketClient] does for client-side
+connections.
+

docs/reference/gio/unix-mounts.md

@@ -0,0 +1,35 @@
+Title: UNIX Mounts
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 2007 Andrew Walton
+SPDX-FileCopyrightText: 2008 Matthias Clasen
+
+# UNIX Mounts
+
+Routines for managing mounted UNIX mount points and paths.
+
+Note that `<gio/gunixmounts.h>` belongs to the UNIX-specific GIO
+interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
+file or the `GioUnix-2.0` GIR namespace when using it.
+
+There are three main classes:
+
+ * [struct@GioUnix.MountEntry]
+ * [struct@GioUnix.MountPoint]
+ * [class@GioUnix.MountMonitor]
+
+Various helper functions for querying mounts:
+
+ * [func@GioUnix.mount_points_get]
+ * [func@GioUnix.MountPoint.at]
+ * [func@GioUnix.mounts_get]
+ * [func@GioUnix.mount_at]
+ * [func@GioUnix.mount_for]
+ * [func@GioUnix.mounts_changed_since]
+ * [func@GioUnix.mount_points_changed_since]
+
+And several helper functions for checking the type of a mount or path:
+
+ * [func@GioUnix.is_mount_path_system_internal]
+ * [func@GioUnix.is_system_fs_type]
+ * [func@GioUnix.is_system_device_path]
+

docs/reference/gio/version.xml.in

@@ -1 +0,0 @@
-@VERSION@

docs/reference/gio/xml/gtkdocentities.ent.in

@@ -1,8 +0,0 @@
-<!ENTITY package "@PACKAGE@">
-<!ENTITY package_bugreport "@PACKAGE_BUGREPORT@">
-<!ENTITY package_name "@PACKAGE_NAME@">
-<!ENTITY package_string "@PACKAGE_STRING@">
-<!ENTITY package_tarname "@PACKAGE_TARNAME@">
-<!ENTITY package_url "@PACKAGE_URL@">
-<!ENTITY package_version "@PACKAGE_VERSION@">
-<!ENTITY package_api_version "@PACKAGE_API_VERSION@">

docs/reference/gio/xml/meson.build

@@ -1,14 +0,0 @@
-ent_conf = configuration_data()
-ent_conf.set('PACKAGE', 'glib')
-ent_conf.set('PACKAGE_BUGREPORT', 'https://gitlab.gnome.org/GNOME/glib/issues/new')
-ent_conf.set('PACKAGE_NAME', 'glib')
-ent_conf.set('PACKAGE_STRING', 'glib')
-ent_conf.set('PACKAGE_TARNAME', 'glib')
-ent_conf.set('PACKAGE_URL', 'FIXME')
-ent_conf.set('PACKAGE_VERSION', glib_version)
-ent_conf.set('PACKAGE_API_VERSION', glib_api_version)
-configure_file(
-  input: 'gtkdocentities.ent.in',
-  output: 'gtkdocentities.ent',
-  configuration: ent_conf
-)

docs/reference/girepository/gi-compile-repository.rst

@@ -0,0 +1,103 @@
+.. _gi-compile-repository(1):
+.. meta::
+   :copyright: Copyright 2010 Johan Dahlin
+   :copyright: Copyright 2015 Ben Boeckel
+   :copyright: Copyright 2013, 2015 Dieter Verfaillie
+   :copyright: Copyright 2018 Emmanuele Bassi
+   :copyright: Copyright 2018 Tomasz Miąsko
+   :copyright: Copyright 2018 Christoph Reiter
+   :copyright: Copyright 2020 Jan Tojnar
+   :copyright: Copyright 2024 Collabora Ltd.
+   :license: LGPL-2.1-or-later
+..
+   This has to be duplicated from above to make it machine-readable by `reuse`:
+   SPDX-FileCopyrightText: 2010 Johan Dahlin
+   SPDX-FileCopyrightText: 2015 Ben Boeckel
+   SPDX-FileCopyrightText: 2013, 2015 Dieter Verfaillie
+   SPDX-FileCopyrightText: 2018 Emmanuele Bassi
+   SPDX-FileCopyrightText: 2018 Tomasz Miąsko
+   SPDX-FileCopyrightText: 2018 Christoph Reiter
+   SPDX-FileCopyrightText: 2020 Jan Tojnar
+   SPDX-FileCopyrightText: 2024 Collabora Ltd.
+   SPDX-License-Identifier: LGPL-2.1-or-later
+
+=====================
+gi-compile-repository
+=====================
+
+----------------
+Typelib compiler
+----------------
+
+:Manual section: 1
+
+
+SYNOPSIS
+========
+
+**gi-compile-repository** [*OPTION*…] *GIRFILE*
+
+
+DESCRIPTION
+===========
+
+gi-compile-repository converts one or more GIR files into one or more typelibs.
+The output will be written to standard output unless the ``--output`` is
+specified.
+
+
+OPTIONS
+=======
+
+``--help``
+    Show help options.
+
+``--output`` *FILENAME*, ``-o`` *FILENAME*
+    Save the resulting output in *FILENAME*.
+
+``--verbose``
+    Show verbose messages.
+
+``--debug``
+    Show debug messages.
+
+``--includedir`` *DIRECTORY*
+    Add *DIRECTORY* to the search path for GIR XML.
+    This option can be used more than once.
+    The first *DIRECTORY* on the command-line will be searched first
+    (highest precedence).
+
+``--shared-library`` *FILENAME*, ``-l`` *FILENAME*
+    Specifies the shared library where the symbols in the typelib can be
+    found. The name of the library should not contain the ending shared
+    library suffix.
+    This option can be used more than once, for typelibs that describe
+    more than one shared library.
+
+``--version``
+    Show program’s version number and exit.
+
+
+EXAMPLE
+=======
+
+::
+    $ gi-compile-repository -o Gio-2.0.typelib /usr/share/gir-1.0/Gio-2.0.gir
+
+
+BUGS
+====
+
+Report bugs at https://gitlab.gnome.org/GNOME/glib/-/issues
+
+
+HOMEPAGE and CONTACT
+====================
+
+https://gi.readthedocs.io/
+
+
+AUTHORS
+=======
+
+Matthias Clasen

docs/reference/girepository/gi-decompile-typelib.rst

@@ -0,0 +1,107 @@
+.. _gi-decompile-typelib(1):
+.. meta::
+   :copyright: Copyright 2008, 2010 Johan Dahlin
+   :copyright: Copyright 2014 Robert Roth
+   :copyright: Copyright 2015 Dieter Verfaillie
+   :copyright: Copyright 2018 Tomasz Miąsko
+   :copyright: Copyright 2018 Christoph Reiter
+   :copyright: Copyright 2020 Jan Tojnar
+   :copyright: Copyright 2024 Collabora Ltd.
+   :license: LGPL-2.1-or-later
+..
+   This has to be duplicated from above to make it machine-readable by `reuse`:
+   SPDX-FileCopyrightText: 2008, 2010 Johan Dahlin
+   SPDX-FileCopyrightText: 2014 Robert Roth
+   SPDX-FileCopyrightText: 2015 Dieter Verfaillie
+   SPDX-FileCopyrightText: 2018 Tomasz Miąsko
+   SPDX-FileCopyrightText: 2018 Christoph Reiter
+   SPDX-FileCopyrightText: 2020 Jan Tojnar
+   SPDX-FileCopyrightText: 2024 Collabora Ltd.
+   SPDX-License-Identifier: LGPL-2.1-or-later
+
+====================
+gi-decompile-typelib
+====================
+
+------------------
+Typelib decompiler
+------------------
+
+:Manual section: 1
+
+
+SYNOPSIS
+========
+
+**gi-decompile-typelib** [*OPTION*…] *TYPELIB* [*TYPELIB*\ …]
+
+
+DESCRIPTION
+===========
+
+gi-decompile-typelib is a GIR decompiler, using the repository API.
+It generates GIR XML files from the compiled binary typelib format.
+The output will be written to standard output unless the ``--output``
+is specified.
+
+The binary typelib format stores a subset of the information available
+in GIR XML, so not all typelibs can be decompiled in this way, and the
+resulting GIR XML might be incomplete.
+
+Normally, GIR XML should be generated from source code, headers and
+shared libraries using `g-ir-scanner(1) <man:g-ir-scanner(1)>`_
+instead of using this tool.
+
+
+OPTIONS
+=======
+
+``--help``
+    Show help options.
+
+``--output`` *FILENAME*, ``-o`` *FILENAME*
+    Save the resulting output in *FILENAME*.
+
+``--includedir`` *DIRECTORY*
+    Add *DIRECTORY* to the search path for typelibs.
+    This option can be used more than once.
+    The first *DIRECTORY* on the command-line will be searched first
+    (highest precedence).
+
+``--all``
+    Show all available information.
+
+``--version``
+    Show program’s version number and exit.
+
+
+EXAMPLE
+=======
+
+::
+    $ libdir=/usr/lib/x86_64-linux-gnu     # or /usr/lib64 or similar
+    $ gi-decompile-typelib -o Gio-2.0.gir \
+      $libdir/girepository-1.0/Gio-2.0.typelib
+
+    $ diff -u /usr/share/gir-1.0/Gio-2.0.gir Gio-2.0.gir
+
+You will see that the original GIR XML contains much more information
+than the decompiled typelib.
+
+
+BUGS
+====
+
+Report bugs at https://gitlab.gnome.org/GNOME/glib/-/issues
+
+
+HOMEPAGE and CONTACT
+====================
+
+https://gi.readthedocs.io/
+
+
+AUTHORS
+=======
+
+Matthias Clasen

docs/reference/girepository/gi-inspect-typelib.rst

@@ -0,0 +1,58 @@
+.. _gio(1):
+.. meta::
+   :copyright: Copyright 2024 Collabora Ltd.
+   :license: LGPL-2.1-or-later
+..
+   This has to be duplicated from above to make it machine-readable by `reuse`:
+   SPDX-FileCopyrightText: 2024 Collabora Ltd.
+   SPDX-License-Identifier: LGPL-2.1-or-later
+
+==================
+gi-inspect-typelib
+==================
+
+-----------------------
+Typelib inspection tool
+-----------------------
+
+SYNOPSIS
+--------
+
+| **gi-inspect-typelib** [*OPTION*\ …] **--print-shlibs** *NAMESPACE*
+| **gi-inspect-typelib** [*OPTION*\ …] **--print-typelibs** *NAMESPACE*
+
+DESCRIPTION
+-----------
+
+**gi-inspect-typelib** displays information about GObject-Introspection
+binary typelib files.
+
+OPTIONS
+-------
+
+``--print-shlibs``
+    Show the shared libraries that implement the *NAMESPACE*.
+
+``--print-typelibs``
+    Show the other typelibs that the *NAMESPACE* depends on.
+
+``--typelib-version``
+    The version of each *NAMESPACE* to inspect.
+    For example, the version of ``Gio-2.0.typelib`` is ``2.0``.
+    If not specified, use the newest available version if there is more
+    than one installed.
+
+EXAMPLE
+-------
+
+On Linux, the ``Gio-2.0`` typelib is implemented by ``libgio-2.0.so.0``::
+
+    $ gi-inspect-typelib --typelib-version 2.0 --print-shlibs Gio
+    shlib: libgio-2.0.so.0
+
+and it depends on GObject-2.0, GLib-2.0 and GModule-2.0::
+
+    $ gi-inspect-typelib --typelib-version 2.0 --print-typelibs Gio
+    typelib: GObject-2.0
+    typelib: GLib-2.0
+    typelib: GModule-2.0

docs/reference/girepository/girepository.toml.in

@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: LGPL-2.1-or-later
+# Copyright 2023 Matthias Clasen
+# Copyright 2023 Philip Withnall
+
+[library]
+name = "Girepository"
+version = "@VERSION@"
+browse_url = "https://gitlab.gnome.org/GNOME/glib/"
+repository_url = "https://gitlab.gnome.org/GNOME/glib.git"
+website_url = "https://www.gtk.org"
+docs_urls = "https://docs.gtk.org/girepository/"
+authors = "GLib Development Team"
+license = "LGPL-2.1-or-later"
+description = "GIRepository is a library providing access to typelibs and introspection data which describes C APIs"
+dependencies = [ "GLib-2.0", "GModule-2.0", "GObject-2.0", "Gio-2.0" ]
+devhelp = true
+search_index = true
+
+  [dependencies."GLib-2.0"]
+  name = "GLib"
+  description = "The base utility library"
+  docs_url = "https://docs.gtk.org/glib/"
+
+  [dependencies."GModule-2.0"]
+  name = "GModule"
+  description = "Portable API for dynamically loading modules"
+  docs_url = "https://docs.gtk.org/gmodule/"
+
+  [dependencies."GObject-2.0"]
+  name = "GObject"
+  description = "The base type system library"
+  docs_url = "https://docs.gtk.org/gobject/"
+
+  [dependencies."Gio-2.0"]
+  name = "Gio"
+  description = "Useful classes for general purpose I/O, networking, IPC, settings, etc."
+  docs_url = "https://docs.gtk.org/gio/"
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[extra]
+urlmap_file = "../urlmap.js"
+# The same order will be used when generating the index
+content_files = [
+  "migrating-gi.md",
+]
+content_images = [
+]

docs/reference/girepository/meson.build

@@ -0,0 +1,56 @@
+if get_option('man-pages').enabled()
+  manpages = [
+    'gi-compile-repository',
+    'gi-decompile-typelib',
+    'gi-inspect-typelib',
+  ]
+  foreach page : manpages
+    custom_target(page + '-man',
+      input: page + '.rst',
+      output: page + '.1',
+      command: [
+        rst2man,
+        rst2man_flags,
+        '@INPUT@',
+      ],
+      capture: true,
+      install: true,
+      install_dir: man1_dir,
+      install_tag: 'doc',
+    )
+  endforeach
+endif
+
+if get_option('documentation') and enable_gir
+  expand_content_files = [
+    'migrating-gi.md',
+  ]
+
+  girepository_toml = configure_file(
+    input: 'girepository.toml.in',
+    output: 'girepository.toml',
+    configuration: toml_conf,
+  )
+
+  custom_target('girepository-docs',
+    input: [ girepository_toml, girepository_gir[0] ],
+    output: 'girepository',
+    command: [
+      gidocgen,
+      'generate',
+      gidocgen_common_args,
+      '--config=@INPUT0@',
+      '--output-dir=@OUTPUT@',
+      '--content-dir=@0@'.format(meson.current_source_dir()),
+      '--add-include-path=@0@'.format(meson.current_build_dir() / '../../../gobject'),
+      '--add-include-path=@0@'.format(meson.current_build_dir() / '../../../gmodule'),
+      '--add-include-path=@0@'.format(meson.current_build_dir() / '../../../gio'),
+      '@INPUT1@',
+    ],
+    build_by_default: true,
+    depend_files: expand_content_files,
+    install: true,
+    install_dir: docs_dir,
+    install_tag: 'doc',
+  )
+endif

docs/reference/girepository/migrating-gi.md

@@ -0,0 +1,112 @@
+Title: Migrating from girepository-1.0 to girepository-2.0
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 2014 GNOME Foundation
+
+# Migrating from girepository-1.0 to girepository-2.0
+
+libgirepository was originally part of
+[gobject-introspection](https://gitlab.gnome.org/GNOME/gobject-introspection/),
+where it was prototyped for a number of years.
+
+Now that it’s considered stable (for a long time), it’s been moved to
+[glib](https://gitlab.gnome.org/GNOME/glib/) in order to simplify the build
+process of the two modules.
+
+As part of this move, the API version has been bumped from 1.0 to 2.0, and some
+fairly straightforward API changes have been made. Note that the GIR version
+was previously 2.0, and is now 3.0 — so the new version of libgirepository uses
+`girepository-2.0.pc` and `GIRepository-3.0.typelib`.
+
+The main change between the two versions of libgirepository is that it now uses
+[type@GObject.TypeInstance] as the basis of its type system, rather than simple
+C struct aliasing. This means that [type@GIRepository.BaseInfo] instances are
+now reference counted using [method@GIRepository.BaseInfo.ref] and
+[method@GIRepository.BaseInfo.unref].
+
+It also means that runtime cast macros such as [func@GIRepository.CALLABLE_INFO]
+are now available. Using these instead of simple C casts can improve the runtime
+type safety of your code.
+
+Stack allocation of some [type@GIRepository.BaseInfo] subtypes is still
+possible, but they must now be cleared using
+[method@GIRepository.BaseInfo.clear] once finished with. Previously this wasn’t
+necessary.
+
+As part of moving the code over, the symbol prefix has changed from `g_` to
+`gi_` — this has affected every API in the library, but trivially.
+
+The types of various function arguments have changed — for example from
+`guint32` to `size_t` for most offsets. This will require minor adjustments in
+your code if integer type warnings are enabled.
+
+## API replacements from version 1.0 to 2.0
+
+| girepository-1.0 | girepository-2.0 |
+|------------------|------------------|
+| `GI_CHECK_VERSION` | [func@GLib.CHECK_VERSION] |
+| `g_arg_info_get_closure` | [method@GIRepository.ArgInfo.get_closure_index] |
+| `g_arg_info_get_destroy` | [method@GIRepository.ArgInfo.get_destroy_index] |
+| `g_arg_info_get_type` | [method@GIRepository.ArgInfo.get_type_info] |
+| `g_arg_info_load_type` | [method@GIRepository.ArgInfo.load_type_info] |
+| - | [method@GIRepository.BaseInfo.ref] and [method@GIRepository.BaseInfo.unref] |
+| `g_base_info_get_type` | Use type checking macros like [func@GIRepository.IS_OBJECT_INFO], or raw [type@GObject.Type]s with [func@GObject.TYPE_FROM_INSTANCE] |
+| `g_info_new` | Removed with no replacement, use [method@GIRepository.find_by_name] and related APIs |
+| `g_callable_info_invoke` arguments | `is_method` and `throws` dropped in [method@GIRepository.CallableInfo.invoke] |
+| `g_constant_info_get_type` | [method@GIRepository.ConstantInfo.get_type_info] |
+| `g_field_info_get_type` | [method@GIRepository.FieldInfo.get_type_info] |
+| `g_object_info_find_method_using_interfaces` and `g_object_info_find_vfunc_using_interfaces` | The `implementor` out argument has been renamed to `declarer` and is now of type [type@GIRepository.BaseInfo] |
+| `g_object_info_get_type_init` | [method@GIRepository.ObjectInfo.get_type_init_function_name] |
+| `g_object_info_get_ref_function` | [method@GIRepository.ObjectInfo.get_ref_function_name] |
+| `g_object_info_get_unref_function` | [method@GIRepository.ObjectInfo.get_unref_function_name] |
+| `g_object_info_get_set_value_function` | [method@GIRepository.ObjectInfo.get_set_value_function_name] |
+| `g_object_info_get_get_value_function` | [method@GIRepository.ObjectInfo.get_get_value_function_name] |
+| `g_property_info_get_type` | [method@GIRepository.PropertyInfo.get_type_info] |
+| `g_registered_type_info_get_type_init` | [method@GIRepository.RegisteredTypeInfo.get_type_init_function_name] |
+| `g_irepository_*` | `gi_repository_*` |
+| `g_irepository_get_default` | Singleton object removed; create separate [class@GIRepository.Repository] instances instead |
+| `g_irepository_get_search_path` and `g_irepository_get_library_path` | Now return arrays rather than linked lists |
+| `g_irepository_enumerate_versions` | Now returns an array rather than a linked list |
+| `g_irepository_get_immediate_dependencies`, `g_irepository_get_dependencies` and `g_irepository_get_loaded_namespaces` | Now additionally return a length argument |
+| `g_irepository_get_shared_library` | [method@GIRepository.get_shared_libraries] |
+| `g_irepository_dump` | Takes structured `input_filename` and `output_filename` arguments rather than a single formatted string |
+| `g_function_invoker_destroy` | `gi_function_invoker_clear()` |
+| `g_struct_info_get_copy_function` | [method@GIRepository.StructInfo.get_copy_function_name] |
+| `g_struct_info_get_free_function` | [method@GIRepository.StructInfo.get_free_function_name] |
+| `g_type_info_get_array_length` and `g_type_info_get_array_fixed_size` | Split success and failure return values out into a new out-argument and return value |
+| `g_type_info_get_array_length` | [method@GIRepository.TypeInfo.get_array_length_index] |
+| `g_typelib_new_from_*` | All replaced with `gi_typelib_new_from_bytes()` |
+| `g_typelib_free` | [type@GIRepository.Typelib] is now a refcounted and boxed type, so use [method@GIRepository.Typelib.unref] |
+| `GI_FUNCTION_THROWS` and `GI_VFUNC_THROWS` | [method@GIRepository.CallableInfo.can_throw_gerror] |
+| `g_union_info_get_discriminator_offset` | Split success and failure return values out into a new out-argument and return value |
+| `g_union_info_get_copy_function` | [method@GIRepository.UnionInfo.get_copy_function_name] |
+| `g_union_info_get_free_function` | [method@GIRepository.UnionInfo.get_free_function_name] |
+| `GIInfoType` | Use [type@GObject.Type] directly |
+| `GI_INFO_TYPE_BOXED` | Dropped in favour of [method@GIRepository.RegisteredTypeInfo.is_boxed] |
+
+## Utility program renames from version 1.0 to 2.0
+
+| girepository-1.0 | girepository-2.0        |
+|------------------|-------------------------|
+| `g-ir-compiler`  | `gi-compile-repository` |
+| `g-ir-generate`  | `gi-decompile-typelib`  |
+| `g-ir-inspect`   | `gi-inspect-typelib`    |
+
+In addition, some command-line options have been changed.
+
+The `--version` option for `g-ir-inspect` has been renamed to
+`--typelib-version` in `gi-inspect-typelib`.
+
+The `--includedir` option to `gi-decompile-typelib` treats the
+given directories as most-important-first, consistent with
+`gi-compile-repository --includedir` and `gcc -I`.
+`g-ir-generate` treated `--includedir` options as least-important-first.
+
+The unimplemented `g-ir-compiler --module` option has been removed in
+`gi-compile-repository`.
+
+The unimplemented `g-ir-generate --shlib` option has been removed in
+`gi-decompile-typelib`.
+
+`gi-inspect-typelib` only accepts one namespace parameter. `g-ir-inspect`
+accepted multiple namespaces, but would only inspect the first one,
+with the others being ignored.

docs/reference/glib/atomic.md

@@ -0,0 +1,75 @@
+Title: Atomic Operations
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 2012 Dan Winship
+
+# Atomic Operations
+
+The following is a collection of compiler macros to provide atomic
+access to integer and pointer-sized values.
+
+The macros that have ‘int’ in the name will operate on pointers to `gint` and
+`guint`.  The macros with ‘pointer’ in the name will operate on pointers to any
+pointer-sized value, including `guintptr`.
+
+There is no support for 64-bit operations on platforms with 32-bit pointers
+because it is not generally possible to perform these operations atomically.
+
+The get, set and exchange operations for integers and pointers
+nominally operate on `gint` and `gpointer`, respectively.  Of the
+arithmetic operations, the ‘add’ operation operates on (and returns)
+signed integer values (`gint` and `gssize`) and the ‘and’, ‘or’, and
+‘xor’ operations operate on (and return) unsigned integer values
+(`guint` and `gsize`).
+
+All of the operations act as a full compiler and (where appropriate)
+hardware memory barrier.  Acquire and release or producer and
+consumer barrier semantics are not available through this API.
+
+It is very important that all accesses to a particular integer or
+pointer be performed using only this API and that different sizes of
+operation are not mixed or used on overlapping memory regions.  Never
+read or assign directly from or to a value — always use this API.
+
+For simple reference counting purposes you should use `gatomicrefcount`
+(see [func@GLib.atomic_ref_count_init]) rather than [func@GLib.atomic_int_inc]
+and [func@GLib.atomic_int_dec_and_test].
+
+Uses of [func@GLib.atomic_int_inc] and [func@GLib.atomic_int_dec_and_test]
+that fall outside of simple counting patterns are prone to
+subtle bugs and occasionally undefined behaviour.  It is also worth
+noting that since all of these operations require global
+synchronisation of the entire machine, they can be quite slow.  In
+the case of performing multiple atomic operations it can often be
+faster to simply acquire a mutex lock around the critical area,
+perform the operations normally and then release the lock.
+
+## Atomic Integer Operations
+
+ * [func@GLib.atomic_int_get]
+ * [func@GLib.atomic_int_set]
+ * [func@GLib.atomic_int_inc]
+ * [func@GLib.atomic_int_dec_and_test]
+ * [func@GLib.atomic_int_compare_and_exchange]
+ * [func@GLib.atomic_int_compare_and_exchange_full]
+ * [func@GLib.atomic_int_exchange]
+ * [func@GLib.atomic_int_add]
+ * [func@GLib.atomic_int_and]
+ * [func@GLib.atomic_int_or]
+ * [func@GLib.atomic_int_xor]
+
+## Atomic Pointer Operations
+
+ * [func@GLib.atomic_pointer_get]
+ * [func@GLib.atomic_pointer_set]
+ * [func@GLib.atomic_pointer_compare_and_exchange]
+ * [func@GLib.atomic_pointer_compare_and_exchange_full]
+ * [func@GLib.atomic_pointer_exchange]
+ * [func@GLib.atomic_pointer_add]
+ * [func@GLib.atomic_pointer_and]
+ * [func@GLib.atomic_pointer_or]
+ * [func@GLib.atomic_pointer_xor]
+
+## Deprecated API
+
+ * [func@GLib.atomic_int_exchange_and_add]
+

docs/reference/glib/auto-cleanup.md

@@ -0,0 +1,291 @@
+Title: Automatic Cleanup
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 2023 Matthias Clasen
+
+# Automatic Cleanup
+
+GLib provides a set of macros that wrap the GCC extension for automatic
+cleanup of variables when they go out of scope.
+
+These macros can only be used with GCC and GCC-compatible C compilers.
+
+## Variable declaration
+
+`g_auto(TypeName)`
+
+:   Helper to declare a variable with automatic cleanup.
+
+    The variable is cleaned up in a way appropriate to its type when the
+    variable goes out of scope. The `TypeName` of the variable must support
+    this.
+
+    The way to clean up the type must have been defined using one of the macros
+    `G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC()` or `G_DEFINE_AUTO_CLEANUP_FREE_FUNC()`.
+
+    This feature is only supported on GCC and clang.  This macro is not
+    defined on other compilers and should not be used in programs that
+    are intended to be portable to those compilers.
+
+    This macro meant to be used with stack-allocated structures and
+    non-pointer types.  For the (more commonly used) pointer version, see
+    `g_autoptr()`.
+
+    This macro can be used to avoid having to do explicit cleanups of
+    local variables when exiting functions.  It often vastly simplifies
+    handling of error conditions, removing the need for various tricks
+    such as `goto out` or repeating of cleanup code.  It is also helpful
+    for non-error cases.
+
+    Consider the following example:
+
+        GVariant *
+        my_func(void)
+        {
+          g_auto(GQueue) queue = G_QUEUE_INIT;
+          g_auto(GVariantBuilder) builder;
+          g_auto(GStrv) strv;
+
+          g_variant_builder_init (&builder, G_VARIANT_TYPE_VARDICT);
+          strv = g_strsplit("a:b:c", ":", -1);
+
+          // ...
+
+          if (error_condition)
+            return NULL;
+
+          // ...
+
+          return g_variant_builder_end (&builder);
+        }
+
+    You must initialize the variable in some way — either by use of an
+    initialiser or by ensuring that an `_init` function will be called on
+    it unconditionally before it goes out of scope.
+
+    Since: 2.44
+
+
+`g_autoptr(TypeName)`
+:   Helper to declare a pointer variable with automatic cleanup.
+
+    The variable is cleaned up in a way appropriate to its type when the
+    variable goes out of scope. The `TypeName` of the variable must support this.
+    The way to clean up the type must have been defined using the macro
+    `G_DEFINE_AUTOPTR_CLEANUP_FUNC()`.
+
+    This feature is only supported on GCC and clang.  This macro is not
+    defined on other compilers and should not be used in programs that
+    are intended to be portable to those compilers.
+
+    This is meant to be used to declare pointers to types with cleanup
+    functions.  The type of the variable is a pointer to `TypeName`.  You
+    must not add your own `*`.
+
+    This macro can be used to avoid having to do explicit cleanups of
+    local variables when exiting functions.  It often vastly simplifies
+    handling of error conditions, removing the need for various tricks
+    such as `goto out` or repeating of cleanup code.  It is also helpful
+    for non-error cases.
+
+    Consider the following example:
+
+        gboolean
+        check_exists(GVariant *dict)
+        {
+          g_autoptr(GVariant) dirname, basename = NULL;
+          g_autofree gchar *path = NULL;
+
+          dirname = g_variant_lookup_value (dict, "dirname", G_VARIANT_TYPE_STRING);
+          if (dirname == NULL)
+            return FALSE;
+
+          basename = g_variant_lookup_value (dict, "basename", G_VARIANT_TYPE_STRING);
+          if (basename == NULL)
+            return FALSE;
+
+          path = g_build_filename (g_variant_get_string (dirname, NULL),
+                                   g_variant_get_string (basename, NULL),
+                                   NULL);
+
+          return g_access (path, R_OK) == 0;
+        }
+
+    You must initialise the variable in some way — either by use of an
+    initialiser or by ensuring that it is assigned to unconditionally
+    before it goes out of scope.
+
+    See also: `g_auto()`, `g_autofree()` and `g_steal_pointer()`.
+
+    Since: 2.44
+
+
+`g_autofree`
+
+:   Macro to add an attribute to pointer variable to ensure automatic
+    cleanup using `g_free()`.
+
+    This macro differs from `g_autoptr()` in that it is an attribute supplied
+    before the type name, rather than wrapping the type definition.  Instead
+    of using a type-specific lookup, this macro always calls `g_free()` directly.
+
+    This means it's useful for any type that is returned from `g_malloc()`.
+
+    Otherwise, this macro has similar constraints as `g_autoptr()`: only
+    supported on GCC and clang, the variable must be initialized, etc.
+
+        gboolean
+        operate_on_malloc_buf (void)
+        {
+          g_autofree guint8* membuf = NULL;
+
+          membuf = g_malloc (8192);
+
+          // Some computation on membuf
+
+          // membuf will be automatically freed here
+          return TRUE;
+        }
+
+    Since: 2.44
+
+
+`g_autolist(TypeName)`
+
+:   Helper to declare a list variable with automatic deep cleanup.
+
+    The list is deeply freed, in a way appropriate to the specified type, when the
+    variable goes out of scope.  The type must support this.
+
+    This feature is only supported on GCC and clang.  This macro is not
+    defined on other compilers and should not be used in programs that
+    are intended to be portable to those compilers.
+
+    This is meant to be used to declare lists of a type with a cleanup
+    function.  The type of the variable is a `GList *`.  You
+    must not add your own `*`.
+
+    This macro can be used to avoid having to do explicit cleanups of
+    local variables when exiting functions.  It often vastly simplifies
+    handling of error conditions, removing the need for various tricks
+    such as `goto out` or repeating of cleanup code.  It is also helpful
+    for non-error cases.
+
+    See also: `g_autoslist()`, `g_autoptr()` and `g_steal_pointer()`.
+
+    Since: 2.56
+
+
+`g_autoslist(TypeName)`
+
+:   Helper to declare a singly linked list variable with automatic deep cleanup.
+
+    The list is deeply freed, in a way appropriate to the specified type, when the
+    variable goes out of scope.  The type must support this.
+
+    This feature is only supported on GCC and clang.  This macro is not
+    defined on other compilers and should not be used in programs that
+    are intended to be portable to those compilers.
+
+    This is meant to be used to declare lists of a type with a cleanup
+    function.  The type of the variable is a `GSList *`.  You
+    must not add your own `*`.
+
+    This macro can be used to avoid having to do explicit cleanups of
+    local variables when exiting functions.  It often vastly simplifies
+    handling of error conditions, removing the need for various tricks
+    such as `goto out` or repeating of cleanup code.  It is also helpful
+    for non-error cases.
+
+    See also: `g_autolist()`, `g_autoptr()` and `g_steal_pointer()`.
+
+    Since: 2.56
+
+
+`g_autoqueue(TypeName)`
+
+:   Helper to declare a double-ended queue variable with automatic deep cleanup.
+
+    The queue is deeply freed, in a way appropriate to the specified type, when the
+    variable goes out of scope.  The type must support this.
+
+    This feature is only supported on GCC and clang.  This macro is not
+    defined on other compilers and should not be used in programs that
+    are intended to be portable to those compilers.
+
+    This is meant to be used to declare queues of a type with a cleanup
+    function.  The type of the variable is a `GQueue *`.  You
+    must not add your own `*`.
+
+    This macro can be used to avoid having to do explicit cleanups of
+    local variables when exiting functions.  It often vastly simplifies
+    handling of error conditions, removing the need for various tricks
+    such as `goto out` or repeating of cleanup code.  It is also helpful
+    for non-error cases.
+
+    See also: `g_autolist()`, `g_autoptr()` and `g_steal_pointer()`.
+
+    Since: 2.62
+
+
+## Type definition
+
+`G_DEFINE_AUTOPTR_CLEANUP_FUNC(TypeName, func)`
+
+:   Defines the appropriate cleanup function for a pointer type.
+
+    The function will not be called if the variable to be cleaned up
+    contains `NULL`.
+
+    This will typically be the `_free()` or `_unref()` function for the given
+    type.
+
+    With this definition, it will be possible to use `g_autoptr()` with
+    the given `TypeName`.
+
+        G_DEFINE_AUTOPTR_CLEANUP_FUNC(GObject, g_object_unref)
+
+    This macro should be used unconditionally; it is a no-op on compilers
+    where cleanup is not supported.
+
+    Since: 2.44
+
+
+`G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC(TypeName, func)`
+
+:   Defines the appropriate cleanup function for a type.
+
+    This will typically be the `_clear()` function for the given type.
+
+    With this definition, it will be possible to use `g_auto()` with
+    the given `TypeName`.
+
+        G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC(GQueue, g_queue_clear)
+
+    This macro should be used unconditionally; it is a no-op on compilers
+    where cleanup is not supported.
+
+    Since: 2.44
+
+
+`G_DEFINE_AUTO_CLEANUP_FREE_FUNC(TypeName, func, none_value)`
+
+:   Defines the appropriate cleanup function for a type.
+
+    With this definition, it will be possible to use `g_auto()` with the
+    given `TypeName`.
+
+    This function will be rarely used.  It is used with pointer-based
+    typedefs and non-pointer types where the value of the variable
+    represents a resource that must be freed.  Two examples are `GStrv`
+    and file descriptors.
+
+    `none_value` specifies the "none" value for the type in question. It
+    is probably something like `NULL` or `-1`.If the variable is found to
+    contain this value then the free function will not be called.
+
+        G_DEFINE_AUTO_CLEANUP_FREE_FUNC(GStrv, g_strfreev, NULL)
+
+    This macro should be used unconditionally; it is a no-op on compilers
+    where cleanup is not supported.
+
+    Since: 2.44

docs/reference/glib/base64.md

@@ -0,0 +1,20 @@
+Title: Base64 Encoding
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 2006, 2009 Matthias Clasen
+
+# Base64 Encoding
+
+Base64 is an encoding that allows a sequence of arbitrary bytes to be
+encoded as a sequence of printable ASCII characters. For the definition
+of Base64, see [RFC 1421](http://www.ietf.org/rfc/rfc1421.txt) or
+[RFC 2045](http://www.ietf.org/rfc/rfc2045.txt).
+Base64 is most commonly used as a MIME transfer encoding for email.
+
+GLib supports incremental encoding using [func@GLib.base64_encode_step] and
+[func@GLib.base64_encode_close]. Incremental decoding can be done with
+[func@GLib.base64_decode_step]. To encode or decode data in one go, use
+[func@GLib.base64_encode] or [func@GLib.base64_decode]. To avoid memory
+allocation when decoding, you can use [func@GLib.base64_decode_inplace].
+
+Support for Base64 encoding was added in GLib 2.12.
+

docs/reference/glib/building.md

@@ -0,0 +1,180 @@
+Title: Building GLib
+
+# Building GLib
+
+GLib uses the [Meson build system](https://mesonbuild.com). The normal
+sequence for compiling and installing the GLib library is thus:
+
+    $ meson setup _build
+    $ meson compile -C _build
+    $ meson install -C _build
+
+On FreeBSD, you will need something more complex:
+
+    $ env CPPFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib -Wl,--disable-new-dtags" \
+    > meson setup \
+    > -Dxattr=false \
+    > -Dinstalled_tests=true \
+    > -Db_lundef=false \
+    > _build
+    $ meson compile -C _build
+
+The standard options provided by Meson may be passed to the `meson` command. Please see the Meson documentation or run:
+
+    meson configure --help
+
+for information about the standard options.
+
+GLib is compiled with
+[strict aliasing](https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#index-fstrict-aliasing)
+disabled. It is strongly recommended that this is not re-enabled by overriding
+the compiler flags, as GLib has not been tested with strict aliasing and cannot
+be guaranteed to work.
+
+## Dependencies
+
+Before you can compile the GLib library, you need to have various other
+tools and libraries installed on your system. If you are building from a
+release archive, you will need a [compliant C
+toolchain](https://gitlab.gnome.org/GNOME/glib/-/blob/main/docs/toolchain-requirements.md),
+Meson, and pkg-config; the requirements are the same when building from a
+Git repository clone of GLib.
+
+- [`pkg-config`](https://www.freedesktop.org/wiki/Software/pkg-config/) is a
+  tool for tracking the compilation flags needed for libraries that are used
+  by the GLib library. (For each library, a small `.pc` text file is
+  installed in a standard location that contains the compilation flags
+  needed for that library along with version number information). 
+
+A UNIX build of GLib requires that the system implements at least the
+original 1990 version of POSIX. Beyond this, it depends on a number of other
+libraries.
+
+- The [GNU libiconv library](http://www.gnu.org/software/libiconv/) is
+  needed to build GLib if your system doesn't have the `iconv()` function
+  for doing conversion between character encodings. Most modern systems
+  should have `iconv()`, however many older systems lack an `iconv()`
+  implementation. On such systems, you must install the libiconv library.
+  This can be found at: http://www.gnu.org/software/libiconv.
+
+  If your system has an `iconv()` implementation but you want to use libiconv
+  instead, make sure it is installed to the default compiler header/library
+  search path (for instance, in `/usr/local/`). The `iconv.h` that libiconv
+  installs hides the system iconv. Meson then detects this, recognizes that the
+  system iconv is unusable and the external one is mandatory, and automatically
+  forces it to be used.
+
+  If you are using the native iconv implementation on Solaris instead of
+  libiconv, you'll need to make sure that you have the converters between
+  locale encodings and UTF-8 installed. At a minimum you'll need the
+  SUNWuiu8 package. You probably should also install the SUNWciu8, SUNWhiu8,
+  SUNWjiu8, and SUNWkiu8 packages.
+
+  The native iconv on Compaq Tru64 doesn't contain support for UTF-8, so
+  you'll need to use GNU libiconv instead. (When using GNU libiconv for
+  GLib, you'll need to use GNU libiconv for GNU gettext as well.) This
+  probably applies to related operating systems as well.
+
+- Python 3.5 or newer is required. Your system Python must conform to
+  [PEP 394](https://www.python.org/dev/peps/pep-0394/) For FreeBSD, this means
+  that the `lang/python3` port must be installed.
+
+- The libintl library from the [GNU
+  gettext](http://www.gnu.org/software/gettext) package is needed if your
+  system doesn't have the `gettext()` functionality for handling message
+  translation databases.
+
+- A thread implementation is needed. The thread support in GLib can be based
+  upon POSIX threads or win32 threads.
+
+- GRegex uses the [PCRE library](http://www.pcre.org/) for regular
+  expression matching. The system version of PCRE is used, unless not available
+  (which is the case on Android), in which case a fallback subproject is used.
+
+- The optional extended attribute support in GIO requires the `getxattr()`
+  family of functions that may be provided by the C library or by the
+  standalone libattr library. To build GLib without extended attribute
+  support, use the `-Dxattr=false` option.
+
+- The optional SELinux support in GIO requires libselinux. To build GLib
+  without SELinux support, use the `-Dselinux=disabled` option.
+
+- The optional support for DTrace requires the `sys/sdt.h` header, which is
+  provided by SystemTap on Linux. To build GLib without DTrace, use the
+  `-Ddtrace=false` option.
+
+- The optional support for SystemTap can be disabled with the
+  `-Dsystemtap=false` option. Additionally, you can control the location
+  where GLib installs the SystemTap probes, using the
+  `-Dtapset_install_dir=DIR` option.
+
+- [gobject-introspection](https://gitlab.gnome.org/GNOME/gobject-introspection/)
+  is needed to generate introspection data for consumption by other projects,
+  and to generate the GLib documentation via
+  [gi-docgen](https://gitlab.gnome.org/GNOME/gi-docgen). There is a dependency
+  cycle between GLib and gobject-introspection. This can be broken by building
+  GLib first with `-Dintrospection=disabled`, then building
+  gobject-introspection against this copy of GLib, then re-building GLib against
+  the new gobject-introspection with `-Dintrospection=enabled`. The GLib API
+  documentation can be built during this second build process if
+  `-Ddocumentation=true` is also set.
+
+## Extra Configuration Options
+
+In addition to the normal options, these additional ones are supported when
+configuring the GLib library:
+
+`--buildtype`
+: This is a standard Meson option which specifies how much debugging and
+  optimization to enable. If the build type is `debug`, `G_ENABLE_DEBUG` will be
+  defined and GLib will be built with additional debug code enabled. You can
+  override this behavior using `-Dglib_debug`.
+
+`-Dforce_posix_threads=true`
+: Normally, Meson should be able to work out the correct thread implementation
+  to use. This option forces POSIX threads to be used even if the platform
+  provides another threading API (for example, on Windows).
+
+`-Dbsymbolic_functions=false` and `-Dbsymbolic_functions=true`
+: By default, GLib uses the `-Bsymbolic-functions` linker flag to avoid
+  intra-library PLT jumps. A side-effect of this is that it is no longer
+  possible to override internal uses of GLib functions with `LD_PRELOAD`.
+  Therefore, it may make sense to turn this feature off in some
+  situations. The `-Dbsymbolic_functions=false` option allows to do that.
+
+`-Ddocumentation=false` and `-Ddocumentation=true`
+: By default, GLib will not build documentation for the library and tools. This
+  option can be used to enable building the documentation.
+
+`-Dman-pages=disabled` and `-Dman-pages=enabled`
+: By default, GLib will detect whether `rst2man` and the necessary DocBook
+  stylesheets are installed. If they are, then it will use them to build
+  the included man pages from the reStructuredText sources. These options can be
+  used to explicitly control whether man pages should be built and used.
+
+`-Dxattr=false` and `-Dxattr=true`
+: By default, GLib will detect whether the `getxattr()` family of functions is
+  available. If it is, then extended attribute support will be included in
+  GIO. These options can be used to explicitly control whether extended
+  attribute support should be included or not. `getxattr()` and friends can be
+  provided by glibc or by the standalone libattr library.
+
+`-Dselinux=auto`, `-Dselinux=enabled` or `-Dselinux=disabled`
+: By default, GLib will detect if libselinux is available and include SELinux
+  support in GIO if it is. These options can be used to explicitly control
+  whether SELinux support should be included.
+
+`-Ddtrace=false` and `-Ddtrace=true`
+: By default, GLib will detect if DTrace support is available, and use it.
+  These options can be used to explicitly control whether DTrace support is
+  compiled into GLib.
+
+`-Dsystemtap=false` and `-Dsystemtap=true`
+: This option requires DTrace support. If it is available, then GLib will also
+  check for the presence of SystemTap.
+
+`-Db_coverage=true` and `-Db_coverage=false`
+: Enable the generation of coverage reports for the GLib tests. This requires
+  the lcov frontend to gcov from the Linux Test Project. To generate a
+  coverage report, use `ninja coverage-html`. The report is placed in the
+  `meson-logs` directory.

docs/reference/glib/building.xml

@@ -1,339 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-]>
-<refentry id="glib-building">
-  <refmeta>
-    <refentrytitle>Compiling the GLib package</refentrytitle>
-    <manvolnum>3</manvolnum>
-    <refmiscinfo>GLib Library</refmiscinfo>
-  </refmeta>
-
-  <refnamediv>
-    <refname>Compiling the GLib Package</refname>
-    <refpurpose>How to compile GLib itself</refpurpose>
-  </refnamediv>
-
-  <refsect1 id="building">
-    <title>Building the Library on UNIX</title>
-    <para>
-      On UNIX, GLib uses the standard <application>Meson</application> build
-      system. The normal sequence for compiling and installing the GLib library
-      is thus:
-
-      <literallayout>
-        <userinput>meson setup _build</userinput>
-        <userinput>meson compile -C _build</userinput>
-        <userinput>meson install -C _build</userinput>
-      </literallayout>
-
-      On FreeBSD:
-      <literallayout>
-        <userinput>env CPPFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib -Wl,--disable-new-dtags" meson setup -Dxattr=false -Dinstalled_tests=true -Db_lundef=false _build</userinput>
-        <userinput>meson compile -C _build</userinput>
-      </literallayout>
-    </para>
-
-    <para>
-      The standard options provided by <application>Meson</application> may be
-      passed to the <command>meson</command> command.  Please see the
-      <application>Meson</application> documentation or run
-      <command>meson configure --help</command> for information about
-      the standard options.
-    </para>
-    <para>
-      GLib is compiled with
-      <ulink url="https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#index-fstrict-aliasing">strict aliasing</ulink>
-      disabled. It is strongly recommended that this is not re-enabled by
-      overriding the compiler flags, as GLib has not been tested with strict
-      aliasing and cannot be guaranteed to work.
-    </para>
-    <para>
-      The GTK documentation contains
-      <ulink url="https://developer.gnome.org/gtk3/stable/gtk-building.html">further details</ulink>
-      about the build process and ways to influence it.
-    </para>
-  </refsect1>
-  <refsect1 id="dependencies">
-    <title>Dependencies</title>
-    <para>
-      Before you can compile the GLib library, you need to have
-      various other tools and libraries installed on your system.
-      If you are building from a release archive, you will need
-      <ulink url="https://gitlab.gnome.org/GNOME/glib/-/blob/main/docs/toolchain-requirements.md">a compliant C toolchain</ulink>,
-      <application>Meson</application>, and <application>pkg-config</application>;
-      the requirements are the same when building from a Git repository clone
-      of GLib.
-    </para>
-    <itemizedlist>
-      <listitem>
-        <para>
-          <ulink url="https://www.freedesktop.org/wiki/Software/pkg-config/">pkg-config</ulink>
-          is a tool for tracking the compilation flags needed for
-          libraries that are used by the GLib library. (For each
-          library, a small <literal>.pc</literal> text file is
-          installed in a standard location that contains the compilation
-          flags needed for that library along with version number
-          information).
-        </para>
-      </listitem>
-    </itemizedlist>
-    <para>
-      A UNIX build of GLib requires that the system implements at
-      least the original 1990 version of POSIX. Beyond this, it
-      depends on a number of other libraries.
-    </para>
-    <itemizedlist>
-      <listitem>
-        <para>
-          The <ulink url="http://www.gnu.org/software/libiconv/">GNU
-          libiconv library</ulink> is needed to build GLib if your
-          system doesn't have the <function>iconv()</function>
-          function for doing conversion between character
-          encodings. Most modern systems should have
-          <function>iconv()</function>, however many older systems lack
-          an <function>iconv()</function> implementation. On such systems,
-          you must install the libiconv library. This can be found at:
-          <ulink url="http://www.gnu.org/software/libiconv">http://www.gnu.org/software/libiconv</ulink>.
-        </para>
-        <para>
-          If your system has an <function>iconv()</function> implementation but
-          you want to use libiconv instead, make sure it is installed to the
-          default compiler header/library search path (for instance, in
-          <filename>/usr/local/</filename>). The <filename>iconv.h</filename>
-          that libiconv installs hides the system iconv. Meson then detects
-          this, recognizes that the system iconv is unusable and the external
-          one is mandatory, and automatically forces it to be used.
-        </para>
-        <para>
-          If you are using the native iconv implementation on Solaris
-          instead of libiconv, you'll need to make sure that you have
-          the converters between locale encodings and UTF-8 installed.
-          At a minimum you'll need the SUNWuiu8 package. You probably
-          should also install the SUNWciu8, SUNWhiu8, SUNWjiu8, and
-          SUNWkiu8 packages.
-        </para>
-        <para>
-          The native iconv on Compaq Tru64 doesn't contain support for
-          UTF-8, so you'll need to use GNU libiconv instead. (When
-          using GNU libiconv for GLib, you'll need to use GNU libiconv
-          for GNU gettext as well.) This probably applies to related
-          operating systems as well.
-        </para>
-      </listitem>
-      <listitem>
-        <para>
-          Python 3.5 or newer is required. Your system Python must
-          conform to <ulink
-          url="https://www.python.org/dev/peps/pep-0394/">PEP 394
-          </ulink>
-          For FreeBSD, this means that the
-          <literal>lang/python3</literal> port must be installed.
-        </para>
-      </listitem>
-      <listitem>
-        <para>
-          The libintl library from the <ulink
-          url="http://www.gnu.org/software/gettext">GNU gettext
-          package</ulink> is needed if your system doesn't have the
-          <function>gettext()</function> functionality for handling
-          message translation databases.
-        </para>
-      </listitem>
-      <listitem>
-        <para>
-          A thread implementation is needed. The thread support in GLib
-          can be based upon POSIX threads or win32 threads.
-        </para>
-      </listitem>
-      <listitem>
-        <para>
-          GRegex uses the <ulink url="http://www.pcre.org/">PCRE library</ulink>
-          for regular expression matching. The system version of PCRE is used,
-          unless not available (which is the case on Android), in which case a
-          fallback subproject is used.
-        </para>
-      </listitem>
-      <listitem>
-        <para>
-          The optional extended attribute support in GIO requires the
-          <function>getxattr()</function> family of functions that may be
-          provided by the C library or by the standalone libattr library. To
-          build GLib without extended attribute support, use the
-          <option>-Dxattr=false</option> option.
-        </para>
-      </listitem>
-      <listitem>
-        <para>
-          The optional SELinux support in GIO requires libselinux.
-          To build GLib without SELinux support, use the
-          <option>-Dselinux=disabled</option> option.
-        </para>
-      </listitem>
-      <listitem>
-        <para>
-          The optional support for DTrace requires the
-          <filename>sys/sdt.h</filename> header, which is provided
-          by SystemTap on Linux. To build GLib without DTrace, use
-          the <option>-Ddtrace=false</option> option.
-        </para>
-      </listitem>
-      <listitem>
-        <para>
-          The optional support for
-          <ulink url="http://sourceware.org/systemtap/">SystemTap</ulink>
-          can be disabled with the <option>-Dsystemtap=false</option>
-          option. Additionally, you can control the location
-          where GLib installs the SystemTap probes, using the
-          <option>-Dtapset_install_dir=DIR</option> option.
-        </para>
-      </listitem>
-    </itemizedlist>
-
-  </refsect1>
-  <refsect1 id="extra-configuration-options">
-    <title>Extra Configuration Options</title>
-
-    <para>
-      In addition to the normal options, these additional ones are supported
-      when configuring the GLib library:
-    </para>
-
-    <formalpara>
-      <title><option>--buildtype</option></title>
-
-      <para>
-        This is a standard <application>Meson</application> option which
-        specifies how much debugging and optimization to enable. If the build
-        type is <literal>debug</literal>,
-        <literal>G_ENABLE_DEBUG</literal> will be defined and GLib will be built
-        with additional debug code enabled. You can override this behavior using
-        <option>-Dglib_debug</option>.
-      </para>
-    </formalpara>
-
-    <formalpara>
-      <title><option>-Dforce_posix_threads=true</option></title>
-
-      <para>
-        Normally, <application>Meson</application> should be able to work out
-        the correct thread implementation to use. This option forces POSIX
-        threads to be used even if the platform provides another threading API
-        (for example, on Windows).
-      </para>
-    </formalpara>
-
-    <formalpara>
-      <title><option>-Dbsymbolic_functions=false</option> and
-        <option>-Dbsymbolic_functions=true</option></title>
-
-      <para>
-        By default, GLib uses the <option>-Bsymbolic-functions</option>
-        linker flag to avoid intra-library PLT jumps. A side-effect
-        of this is that it is no longer possible to override
-        internal uses of GLib functions with
-        <envar>LD_PRELOAD</envar>. Therefore, it may make
-        sense to turn this feature off in some situations.
-        The <option>-Dbsymbolic_functions=false</option> option allows
-        to do that.
-      </para>
-    </formalpara>
-
-    <formalpara>
-      <title><option>-Dgtk_doc=false</option> and
-        <option>-Dgtk_doc=true</option></title>
-
-      <para>
-        By default, GLib will detect whether the
-        <application>gtk-doc</application> package is installed.
-        If it is, then it will use it to extract and build the
-        documentation for the GLib library. These options
-        can be used to explicitly control whether
-        <application>gtk-doc</application> should be
-        used or not. If it is not used, the distributed,
-        pre-generated HTML files will be installed instead of
-        building them on your machine.
-      </para>
-    </formalpara>
-
-    <formalpara>
-      <title><option>-Dman=false</option> and
-        <option>-Dman=true</option></title>
-
-      <para>
-        By default, GLib will detect whether <application>xsltproc</application>
-        and the necessary DocBook stylesheets are installed.
-        If they are, then it will use them to rebuild the included
-        man pages from the XML sources. These options can be used
-        to explicitly control whether man pages should be rebuilt
-        used or not. The distribution includes pre-generated man
-        pages.
-      </para>
-    </formalpara>
-
-    <formalpara>
-      <title><option>-Dxattr=false</option> and
-        <option>-Dxattr=true</option></title>
-
-      <para>
-        By default, GLib will detect whether the
-        <function>getxattr()</function>
-        family of functions is available. If it is, then extended
-        attribute support will be included in GIO. These options can
-        be used to explicitly control whether extended attribute
-        support should be included or not. <function>getxattr()</function>
-        and friends can be provided by glibc or by the standalone
-        libattr library.
-      </para>
-    </formalpara>
-
-    <formalpara>
-      <title><option>-Dselinux=auto</option>,
-        <option>-Dselinux=enabled</option> or
-        <option>-Dselinux=disabled</option></title>
-
-      <para>
-        By default, GLib will detect if libselinux is available and
-        include SELinux support in GIO if it is. These options can be
-        used to explicitly control whether SELinux support should
-        be included.
-      </para>
-    </formalpara>
-
-    <formalpara>
-      <title><option>-Ddtrace=false</option> and
-        <option>-Ddtrace=true</option></title>
-
-      <para>
-        By default, GLib will detect if DTrace support is available, and use it.
-        These options can be used to explicitly control whether DTrace support
-        is compiled into GLib.
-      </para>
-    </formalpara>
-
-    <formalpara>
-      <title><option>-Dsystemtap=false</option> and
-        <option>-Dsystemtap=true</option></title>
-
-      <para>
-        This option requires DTrace support. If it is available, then
-        GLib will also check for the presence of SystemTap.
-      </para>
-    </formalpara>
-
-    <formalpara>
-      <title><option>-Db_coverage=true</option> and
-        <option>-Db_coverage=false</option></title>
-
-      <para>
-        Enable the generation of coverage reports for the GLib tests.
-        This requires the lcov frontend to gcov from the
-        <ulink url="http://ltp.sourceforge.net">Linux Test Project</ulink>.
-        To generate a coverage report, use
-        <command>ninja coverage-html</command>. The report is placed in the
-        <filename>meson-logs</filename> directory.
-      </para>
-    </formalpara>
-  </refsect1>
-
-</refentry>

docs/reference/glib/changes.xml

@@ -1,174 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-]>
-<refentry id="glib-changes" revision="17 Jan 2002">
-<refmeta>
-<refentrytitle>Changes to GLib</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>Changes to GLib</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>Changes to GLib</refname>
-<refpurpose>
-Incompatible changes made between successive versions of GLib
-</refpurpose>
-</refnamediv>
-
-
-<refsect1>
-<title>Incompatible changes from 2.0 to 2.2</title>
-
-<itemizedlist>
-
-<listitem>
-<para>
-GLib changed the seeding algorithm for the pseudo-random number
-generator Mersenne Twister, as used by <structname>GRand</structname>
-and <structname>GRandom</structname>. This was necessary, because some
-seeds would yield very bad pseudo-random streams. Also the
-pseudo-random integers generated by
-<function>g_rand*_int_range()</function> will have a
-slightly better equal distribution with the new version of GLib.
-</para>
-
-<para>
-Further information can be found at the website of the Mersenne
-Twister random number generator at <ulink
-url="http://www.math.keio.ac.jp/~matumoto/emt.html">http://www.math.keio.ac.jp/~matumoto/emt.html</ulink>.
-</para> 
-
-<para>
-The original seeding and generation algorithms, as found in GLib
-2.0.x, can be used instead of the new ones by setting the environment
-variable <envar>G_RANDOM_VERSION</envar> to the value of '2.0'. Use
-the GLib-2.0 algorithms only if you have sequences of numbers generated
-with Glib-2.0 that you need to reproduce exactly.  
-</para> 
-
-</listitem>
-
-</itemizedlist>
-
-</refsect1>
-
-<refsect1>
-<title>Incompatible changes from 1.2 to 2.0</title>
-
-<itemizedlist>
-
-<listitem>
-<para>
-The event loop functionality <structname>GMain</structname> has extensively 
-been revised to support multiple separate main loops in separate threads. 
-All sources (timeouts, idle functions, etc.) are associated with a 
-<structname>GMainContext</structname>.
-</para>
-
-<para>
-Compatibility functions exist so that most application code dealing with
-the main loop will continue to work. However, code that creates new custom 
-types of sources will require modification.
-</para>
-
-<para>
-The main changes here are:
-
-  <itemizedlist>
-
-  <listitem>
-  <para>
-   Sources are now exposed as <type>GSource *</type>, rather than simply as 
-   numeric ids.
-  </para>
-  </listitem>
-  
-  <listitem>
-  <para>
-   New types of sources are created by structure "derivation" from 
-   <structname>GSource</structname>, so the <literal>source_data</literal> 
-   parameter to the <structname>GSource</structname> virtual functions has been
-   replaced with a <type>GSource *</type>.
-  </para>
-  </listitem>
-  
-  <listitem>
-  <para>
-   Sources are first created, then later added to a specific 
-   <structname>GMainContext</structname>. 
-  </para>
-  </listitem>
-  
-  <listitem>
-  <para>
-   Dispatching has been modified so both the callback and data are passed
-   in to the <function>dispatch()</function> virtual function.
-  </para>
-  </listitem>
-
-  </itemizedlist>
-  To go along with this change, the vtable for 
-  <structname>GIOChannel</structname> has changed and
-  <function>add_watch()</function> has been replaced by 
-  <function>create_watch()</function>.
-</para>
-</listitem>
-
-<listitem>
-<para>
-<function>g_list_foreach()</function> and 
-<function>g_slist_foreach()</function> have been changed so they
-are now safe against removal of the current item, not the next item.
-</para>
-
-<para>
-It's not recommended to mutate the list in the callback to these
-functions in any case.
-</para>
-</listitem>
-
-<listitem>
-<para>
-<structname>GDate</structname> now works in UTF-8, not in the current locale. 
-If you want to use it with the encoding of the locale, you need to convert 
-strings using <function>g_locale_to_utf8()</function> first.
-</para>
-</listitem>
-
-<listitem>
-<para>
-<function>g_strsplit()</function> has been fixed to:
-
-  <itemizedlist>
-  <listitem>
-  <para>
-   include trailing empty tokens, rather than stripping them
-  </para>
-  </listitem>
-  <listitem>
-  <para>
-   split into a maximum of <literal>max_tokens</literal> tokens, rather 
-   than <literal>max_tokens + 1</literal>
-  </para>
-  </listitem>
-  </itemizedlist>
-
-  Code depending on either of these bugs will need to be fixed.
-</para>
-</listitem>
-
-<listitem>
-<para>
-Deprecated functions that got removed:
-<function>g_set_error_handler()</function>, 
-<function>g_set_warning_handler()</function>,
-<function>g_set_message_handler()</function>, use 
-<function>g_log_set_handler()</function> instead.
-</para>
-</listitem>
-</itemizedlist>
-
-</refsect1>
-
-</refentry>

docs/reference/glib/character-set.md

@@ -0,0 +1,91 @@
+Title: Character Set Conversions
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 2010, 2012, 2014 Matthias Clasen
+
+# Character Set Conversions
+
+The [`func@GLib.convert`] family of function wraps the functionality of
+iconv(). In addition to pure character set conversions, GLib has functions
+to deal with the extra complications of encodings for file names.
+
+## File Name Encodings
+
+Historically, UNIX has not had a defined encoding for file names: a file
+name is valid as long as it does not have path separators in it ("/").
+However, displaying file names may require conversion: from the character
+set in which they were created, to the character set in which the
+application operates. Consider the Spanish file name "Presentación.sxi". If
+the application which created it uses ISO-8859-1 for its encoding,
+
+```
+Character:  P  r  e  s  e  n  t  a  c  i  ó  n  .  s  x  i
+Hex code:   50 72 65 73 65 6e 74 61 63 69 f3 6e 2e 73 78 69
+```
+
+However, if the application use UTF-8, the actual file name on disk would
+look like this:
+
+```
+Character:  P  r  e  s  e  n  t  a  c  i  ó     n  .  s  x  i
+Hex code:   50 72 65 73 65 6e 74 61 63 69 c3 b3 6e 2e 73 78 69
+```
+
+Glib uses UTF-8 for its strings, and GUI toolkits like GTK that use GLib do
+the same thing. If you get a file name from the file system, for example,
+from `readdir()` or from [`method@GLib.Dir.read_name`], and you wish to
+display the file name to the user, you will need to convert it into UTF-8.
+The opposite case is when the user types the name of a file they wish to
+save: the toolkit will give you that string in UTF-8 encoding, and you will
+need to convert it to the character set used for file names before you can
+create the file with `open()` or `fopen()`.
+
+By default, GLib assumes that file names on disk are in UTF-8 encoding. This
+is a valid assumption for file systems which were created relatively
+recently: most applications use UTF-8 encoding for their strings, and that
+is also what they use for the file names they create. However, older file
+systems may still contain file names created in "older" encodings, such as
+ISO-8859-1. In this case, for compatibility reasons, you may want to
+instruct GLib to use that particular encoding for file names rather than
+UTF-8. You can do this by specifying the encoding for file names in the
+`G_FILENAME_ENCODING` environment variable. For example, if your installation
+uses ISO-8859-1 for file names, you can put this in your `~/.profile`:
+
+    export G_FILENAME_ENCODING=ISO-8859-1
+
+GLib provides the functions [`func@GLib.filename_to_utf8`] and
+[`func@GLib.filename_from_utf8`] to perform the necessary conversions. These
+functions convert file names from the encoding specified in
+`G_FILENAME_ENCODING` to UTF-8 and vice-versa.  This diagram illustrates how
+these functions are used to convert between UTF-8 and the encoding for file
+names in the file system.
+
+## Conversion between file name encodings
+
+![](file-name-encodings.png)
+
+## Checklist for Application Writers
+
+This section is a practical summary of the detailed things to do to make
+sure your applications process file name encodings correctly.
+
+1. If you get a file name from the file system from a function such as
+   `readdir()` or `gtk_file_chooser_get_filename()`, you do not need to do
+   any conversion to pass that file name to functions like `open()`,
+   `rename()`, or `fopen()` -- those are "raw" file names which the file
+   system understands.
+2. If you need to display a file name, convert it to UTF-8 first by using
+   [`func@GLib.filename_to_utf8`]. If conversion fails, display a string
+   like "Unknown file name". Do not convert this string back into the
+   encoding used for file names if you wish to pass it to the file system;
+   use the original file name instead.
+3. For example, the document window of a word processor could display
+   "Unknown file name" in its title bar but still let the user save the
+   file, as it would keep the raw file name internally. This can happen if
+   the user has not set the `G_FILENAME_ENCODING` environment variable even
+   though he has files whose names are not encoded in UTF-8.
+4. If your user interface lets the user type a file name for saving or
+   renaming, convert it to the encoding used for file names in the file
+   system by using [`func@GLib.filename_from_utf8`]. Pass the converted file
+   name to functions like `fopen()`. If conversion fails, ask the user to
+   enter a different file name. This can happen if the user types Japanese
+   characters when `G_FILENAME_ENCODING` is set to ISO-8859-1, for example.

docs/reference/glib/checked-math.md

@@ -0,0 +1,30 @@
+Title: Bounds-checking Integer Arithmetic
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 2015 Allison Lortie
+
+# Bounds-checking Integer Arithmetic
+
+GLib offers a set of macros for doing additions and multiplications
+of unsigned integers, with checks for overflows.
+
+The helpers all have three arguments.  A pointer to the destination
+is always the first argument and the operands to the operation are
+the other two.
+
+Following standard GLib convention, the helpers return true in case
+of success (ie: no overflow).
+
+The helpers may be macros, normal functions or inlines.  They may be
+implemented with inline assembly or compiler intrinsics where
+available.
+
+Since: 2.48
+
+The APIs are:
+
+ * [func@GLib.uint_checked_add]
+ * [func@GLib.uint_checked_mul]
+ * [func@GLib.uint64_checked_add]
+ * [func@GLib.uint64_checked_mul]
+ * [func@GLib.size_checked_add]
+ * [func@GLib.size_checked_mul]

docs/reference/glib/compiling.md

@@ -0,0 +1,71 @@
+Title: Compiling GLib Applications
+
+# Compiling GLib Applications
+
+To compile a GLib application, you need to tell the compiler where to find
+the GLib header files and libraries. This is done with the
+[`pkg-config`](https://www.freedesktop.org/wiki/Software/pkg-config/)
+utility.
+
+The following interactive shell session demonstrates how pkg-config is used
+(the actual output on your system may be different):
+
+    $ pkg-config --cflags glib-2.0
+    -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include
+    $ pkg-config --libs glib-2.0
+    -L/usr/lib -lm -lglib-2.0
+
+See the `pkg-config` website for more information about `pkg-config`.
+
+If your application uses or GObject features, it must be compiled and linked
+with the options returned by the following `pkg-config` invocation:
+
+    $ pkg-config --cflags --libs gobject-2.0
+
+If your application uses modules, it must be compiled and linked with the
+options returned by one of the following pkg-config invocations:
+
+    $ pkg-config --cflags --libs gmodule-no-export-2.0
+    $ pkg-config --cflags --libs gmodule-2.0
+
+The difference between the two is that `gmodule-2.0` adds `--export-dynamic`
+to the linker flags, which is often not needed.
+
+The simplest way to compile a program is to use the "backticks" feature of
+the shell. If you enclose a command in backticks (not single quotes), then
+its output will be substituted into the command line before execution. So to
+compile a GLib Hello, World, you would type the following:
+
+    $ cc `pkg-config --cflags glib-2.0` hello.c -o hello `pkg-config --libs glib-2.0`
+
+Deprecated GLib functions are annotated to make the compiler emit warnings
+when they are used (e.g. with GCC, you need to use the
+`-Wdeprecated-declarations option`). If these warnings are problematic, they
+can be turned off by defining the preprocessor symbol
+`GLIB_DISABLE_DEPRECATION_WARNINGS` by using the commandline option
+`-DGLIB_DISABLE_DEPRECATION_WARNINGS`
+
+GLib deprecation annotations are versioned; by defining the macros
+`GLIB_VERSION_MIN_REQUIRED` and `GLIB_VERSION_MAX_ALLOWED`, you can specify the
+range of GLib versions whose API you want to use. APIs that were deprecated
+before or introduced after this range will trigger compiler warnings.
+
+Since GLib 2.62, the older deprecation mechanism of hiding deprecated
+interfaces entirely from the compiler by using the preprocessor symbol
+`G_DISABLE_DEPRECATED` has been removed. All deprecations are now handled
+using the above mechanism.
+
+The recommended way of using GLib has always been to only include the
+toplevel headers `glib.h`, `glib-object.h`, `gio.h`. Starting with 2.32, GLib
+enforces this by generating an error when individual headers are directly
+included.
+
+Still, there are some exceptions; these headers have to be included
+separately:
+
+- `gmodule.h`
+- `glib-unix.h`
+- `glib/gi18n-lib.h` or `glib/gi18n.h` (see the section on
+  [Internationalization](i18n.html))
+- `glib/gprintf.h` and `glib/gstdio.h` (we don't want to pull in all of
+  stdio)

docs/reference/glib/compiling.xml

@@ -1,125 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-]>
-<refentry id="glib-compiling" revision="17 Jan 2002">
-<refmeta>
-<refentrytitle>Compiling GLib Applications</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>GLib Library</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>Compiling GLib Applications</refname>
-<refpurpose>
-How to compile your GLib application
-</refpurpose>
-</refnamediv>
-
-<refsect1>
-<title>Compiling GLib Applications on UNIX</title>
-
-<para>
-To compile a GLib application, you need to tell the compiler where to
-find the GLib header files and libraries. This is done with the
-<application>pkg-config</application> utility.
-</para>
-<para>
-The following interactive shell session demonstrates how
-<application>pkg-config</application> is used (the actual output on
-your system may be different):
-<programlisting>
-$ pkg-config --cflags glib-2.0
- -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include
-$ pkg-config --libs glib-2.0
- -L/usr/lib -lm -lglib-2.0
-</programlisting>
-</para>
-<para>
-See the <ulink url="http://www.freedesktop.org/wiki/Software/pkg-config">pkg-config website</ulink>
-for more information about <application>pkg-config</application>.
-</para>
-<para>
-If your application uses or <structname>GObject</structname>
-features, it must be compiled and linked with the options returned
-by the following <application>pkg-config</application> invocation:
-<programlisting>
-$ pkg-config --cflags --libs gobject-2.0
-</programlisting>
-</para>
-<para>
-If your application uses modules, it must be compiled and linked
-with the options returned by one of the following
-<application>pkg-config</application> invocations:
-<programlisting>
-$ pkg-config --cflags --libs gmodule-no-export-2.0
-$ pkg-config --cflags --libs gmodule-2.0
-</programlisting>
-The difference between the two is that gmodule-2.0 adds
-<option>--export-dynamic</option> to the linker flags,
-which is often not needed.
-</para>
-<para>
-The simplest way to compile a program is to use command substitution
-feature of a shell. A command written in the format
-<literal>$(command)</literal> gets substituted into the command line
-before execution. So to compile a GLib Hello, World, you would type
-the following:
-<programlisting>
-$ cc hello.c $(pkg-config --cflags --libs glib-2.0) -o hello
-</programlisting>
-</para>
-<note><para>
-Note that the name of the file must come before the other options
-(such as <emphasis>pkg-config</emphasis>), or else you may get an
-error from the linker.
-</para></note>
-
-<para>
-Deprecated GLib functions are annotated to make the compiler
-emit warnings when they are used (e.g. with gcc, you need to use
-the -Wdeprecated-declarations option). If these warnings are
-problematic, they can be turned off by defining the preprocessor
-symbol %GLIB_DISABLE_DEPRECATION_WARNINGS by using the commandline
-option <literal>-DGLIB_DISABLE_DEPRECATION_WARNINGS</literal>
-</para>
-
-<para>
-GLib deprecation annotations are versioned; by defining the
-macros %GLIB_VERSION_MIN_REQUIRED and %GLIB_VERSION_MAX_ALLOWED,
-you can specify the range of GLib versions whose API you want
-to use. APIs that were deprecated before or introduced after
-this range will trigger compiler warnings.
-</para>
-
-<para>
-Since GLib 2.62, the older deprecation mechanism of hiding deprecated interfaces
-entirely from the compiler by using the preprocessor symbol
-<literal>G_DISABLE_DEPRECATED</literal> has been removed. All deprecations
-are now handled using the above mechanism.
-</para>
-
-<para>
-The recommended way of using GLib has always been to only include the
-toplevel headers <filename>glib.h</filename>,
-<filename>glib-object.h</filename>, <filename>gio.h</filename>.
-Starting with 2.32, GLib enforces this by generating an error
-when individual headers are directly included.
-</para>
-
-<para>
-Still, there are some exceptions; these headers have to be included
-separately:
-<filename>gmodule.h</filename>,
-<filename>glib-unix.h</filename>,
-<filename>glib/gi18n-lib.h</filename> or
-<filename>glib/gi18n.h</filename> (see
-the <link linkend="glib-I18N">Internationalization section</link>),
-<filename>glib/gprintf.h</filename> and
-<filename>glib/gstdio.h</filename>
-(we don't want to pull in all of stdio).
-</para>
-
-</refsect1>
-
-</refentry>

docs/reference/glib/conversion-macros.md

@@ -0,0 +1,281 @@
+Title: Conversion Macros
+
+# Conversion Macros
+
+## Type Conversion
+
+Many times GLib, GTK, and other libraries allow you to pass "user data" to a
+callback, in the form of a void pointer. From time to time you want to pass
+an integer instead of a pointer. You could allocate an integer, with
+something like:
+
+```c
+int *ip = g_new (int, 1);
+*ip = 42;
+```
+
+But this is inconvenient, and it's annoying to have to free the memory at
+some later time.
+
+Pointers are always at least 32 bits in size (on all platforms GLib intends
+to support). Thus you can store at least 32-bit integer values in a pointer
+value. Naively, you might try this, but it's incorrect:
+
+```c
+gpointer p;
+int i;
+p = (void*) 42;
+i = (int) p;
+```
+
+Again, that example was not correct, don't copy it.
+
+The problem is that on some systems you need to do this:
+
+```c
+gpointer p;
+int i;
+p = (void*) (long) 42;
+i = (int) (long) p;
+```
+
+The GLib macros `GPOINTER_TO_INT()`, `GINT_TO_POINTER()`, etc. take care to
+do the right thing on every platform.
+
+**Warning**: You may not store pointers in integers. This is not portable in
+any way, shape or form. These macros only allow storing integers in
+pointers, and only preserve 32 bits of the integer; values outside the range
+of a 32-bit integer will be mangled.
+
+
+``GINT_TO_POINTER(value)``, ``GPOINTER_TO_INT(value)``
+: Stuffs an integer into a pointer type, and vice versa. Remember, you may not
+  store pointers in integers. This is not portable in any way, shape or form.
+  These macros only allow storing integers in pointers, and only preserve 32
+  bits of the integer; values outside the range of a 32-bit integer will be
+  mangled.
+
+``GUINT_TO_POINTER(value)``, ``GPOINTER_TO_UINT(value)``
+: Stuffs an unsigned integer into a pointer type, and vice versa.
+
+``GSIZE_TO_POINTER(value)``, ``GPOINTER_TO_SIZE(value)``
+: Stuffs a `size_t` into a pointer type, and vice versa.
+
+## Byte Order Conversion
+
+These macros provide a portable way to determine the host byte order and to
+convert values between different byte orders.
+
+The byte order is the order in which bytes are stored to create larger data
+types such as the #gint and #glong values.  The host byte order is the byte
+order used on the current machine.
+
+Some processors store the most significant bytes (i.e. the bytes that hold
+the largest part of the value) first. These are known as big-endian
+processors. Other processors (notably the x86 family) store the most
+significant byte last. These are known as little-endian processors.
+
+Finally, to complicate matters, some other processors store the bytes in a
+rather curious order known as PDP-endian. For a 4-byte word, the 3rd most
+significant byte is stored first, then the 4th, then the 1st and finally the
+2nd.
+
+Obviously there is a problem when these different processors communicate
+with each other, for example over networks or by using binary file formats.
+This is where these macros come in. They are typically used to convert
+values into a byte order which has been agreed on for use when communicating
+between different processors. The Internet uses what is known as 'network
+byte order' as the standard byte order (which is in fact the big-endian byte
+order).
+
+Note that the byte order conversion macros may evaluate their arguments
+multiple times, thus you should not use them with arguments which have
+side-effects.
+
+`G_BYTE_ORDER`
+: The host byte order. This can be either `G_LITTLE_ENDIAN` or `G_BIG_ENDIAN`.
+
+`G_LITTLE_ENDIAN`
+: Specifies the little endian byte order.
+
+`G_BIG_ENDIAN`
+: Specifies the big endian byte order.
+
+`G_PDP_ENDIAN`
+: Specifies the PDP endian byte order.
+
+### Signed
+
+`GINT_FROM_BE(value)`
+: Converts an `int` value from big-endian to host byte order.
+
+`GINT_FROM_LE(value)`
+: Converts an `int` value from little-endian to host byte order.
+
+`GINT_TO_BE(value)`
+: Converts an `int` value from host byte order to big-endian.
+
+`GINT_TO_LE(value)`
+: Converts an `int` value from host byte order to little-endian.
+
+`GLONG_FROM_BE(value)`
+: Converts a `long` value from big-endian to the host byte order.
+
+`GLONG_FROM_LE(value)`
+: Converts a `long` value from little-endian to host byte order.
+
+`GLONG_TO_BE(value)`
+: Converts a `long` value from host byte order to big-endian.
+
+`GLONG_TO_LE(value)`
+: Converts a `long` value from host byte order to little-endian.
+
+`GSSIZE_FROM_BE(value)`
+: Converts a `ssize_t` value from big-endian to host byte order.
+
+`GSSIZE_FROM_LE(value)`
+: Converts a `ssize_t` value from little-endian to host byte order.
+
+`GSSIZE_TO_BE(value)`
+: Converts a `ssize_t` value from host byte order to big-endian.
+
+`GSSIZE_TO_LE(value)`
+: Converts a `ssize_t` value from host byte order to little-endian.
+
+`GINT16_FROM_BE(value)`
+: Converts an `int16_t` value from big-endian to host byte order.
+
+`GINT16_FROM_LE(value)`
+: Converts an `int16_t` value from little-endian to host byte order.
+
+`GINT16_TO_BE(value)`
+: Converts an `int16_t` value from host byte order to big-endian.
+
+`GINT16_TO_LE(value)`
+: Converts an `int16_t` value from host byte order to little-endian.
+
+`GINT32_FROM_BE(value)`
+: Converts an `int32_t` value from big-endian to host byte order.
+
+`GINT32_FROM_LE(value)`
+: Converts an `int32_t` value from little-endian to host byte order.
+
+`GINT32_TO_BE(value)`
+: Converts an `int32_t` value from host byte order to big-endian.
+
+`GINT32_TO_LE(value)`
+: Converts an `int32_t` value from host byte order to little-endian.
+
+`GINT64_FROM_BE(value)`
+: Converts an `int64_t` value from big-endian to host byte order.
+
+`GINT64_FROM_LE(value)`
+: Converts an `int64_t` value from little-endian to host byte order.
+
+`GINT64_TO_BE(value)`
+: Converts an `int64_t` value from host byte order to big-endian.
+
+`GINT64_TO_LE(value)`
+: Converts an `int64_t` value from host byte order to little-endian.
+
+### Unsigned
+
+`GUINT_FROM_BE(value)`
+: Converts an `unsigned int` value from big-endian to host byte order.
+
+`GUINT_FROM_LE(value)`
+: Converts an `unsigned int` value from little-endian to host byte order.
+
+`GUINT_TO_BE(value)`
+: Converts an `unsigned int` value from host byte order to big-endian.
+
+`GUINT_TO_LE(value)`
+: Converts an `unsigned int` value from host byte order to little-endian.
+
+`GULONG_FROM_BE(value)`
+: Converts an `unsigned long` value from big-endian to host byte order.
+
+`GULONG_FROM_LE(value)`
+: Converts an `unsigned long` value from little-endian to host byte order.
+
+`GULONG_TO_BE(value)`
+: Converts an `unsigned long` value from host byte order to big-endian.
+
+`GULONG_TO_LE(value)`
+: Converts an `unsigned long` value from host byte order to little-endian.
+
+`GSIZE_FROM_BE(value)`
+: Converts a `size_t` value from big-endian to the host byte order.
+
+`GSIZE_FROM_LE(value)`
+: Converts a `size_t` value from little-endian to host byte order.
+
+`GSIZE_TO_BE(value)`
+: Converts a `size_t` value from host byte order to big-endian.
+
+`GSIZE_TO_LE(value)`
+: Converts a `size_t` value from host byte order to little-endian.
+
+`GUINT16_FROM_BE(value)`
+: Converts an `uint16_t` value from big-endian to host byte order.
+
+`GUINT16_FROM_LE(value)`
+: Converts an `uint16_t` value from little-endian to host byte order.
+
+`GUINT16_TO_BE(value)`
+: Converts an `uint16_t` value from host byte order to big-endian.
+
+`GUINT16_TO_LE(value)`
+: Converts an `uint16_t` value from host byte order to little-endian.
+
+`GUINT32_FROM_BE(value)`
+: Converts an `uint32_t` value from big-endian to host byte order.
+
+`GUINT32_FROM_LE(value)`
+: Converts an `uint32_t` value from little-endian to host byte order.
+
+`GUINT32_TO_BE(value)`
+: Converts an `uint32_t` value from host byte order to big-endian.
+
+`GUINT32_TO_LE(value)`
+: Converts an `uint32_t` value from host byte order to little-endian.
+
+`GUINT64_FROM_BE(value)`
+: Converts an `uint64_t` value from big-endian to host byte order.
+
+`GUINT64_FROM_LE(value)`
+: Converts an `uint64_t` value from little-endian to host byte order.
+
+`GUINT64_TO_BE(value)`
+: Converts an `uint64_t` value from host byte order to big-endian.
+
+`GUINT64_TO_LE(value)`
+: Converts an `uint64_t` value from host byte order to little-endian.
+
+`GUINT16_SWAP_BE_PDP(value)`
+: Converts an `uint16_t` value between big-endian and pdp-endian byte order.
+  The conversion is symmetric so it can be used both ways.
+
+`GUINT16_SWAP_LE_BE(value)`
+: Converts an `uint16_t` value between little-endian and big-endian byte order.
+  The conversion is symmetric so it can be used both ways.
+
+`GUINT16_SWAP_LE_PDP(value)`
+: Converts an `uint16_t` value between little-endian and pdp-endian byte order.
+  The conversion is symmetric so it can be used both ways.
+
+`GUINT32_SWAP_BE_PDP(value)`
+: Converts an `uint32_t` value between big-endian and pdp-endian byte order.
+  The conversion is symmetric so it can be used both ways.
+
+`GUINT32_SWAP_LE_BE(value)`
+: Converts an `uint32_t` value between little-endian and big-endian byte order.
+  The conversion is symmetric so it can be used both ways.
+
+`GUINT32_SWAP_LE_PDP(value)`
+: Converts an `uint32_t` value between little-endian and pdp-endian byte order.
+  The conversion is symmetric so it can be used both ways.
+
+`GUINT64_SWAP_LE_BE(value)`
+: Converts a `uint64_t` value between little-endian and big-endian byte order.
+  The conversion is symmetric so it can be used both ways.

docs/reference/glib/cross-compiling.md

@@ -0,0 +1,88 @@
+Title: Cross-compiling the GLib package
+
+# Cross-compiling the GLib Package
+
+## Building the Library for a different architecture
+
+Cross-compilation is the process of compiling a program or library on a
+different architecture or operating system then it will be run upon. GLib is
+slightly more difficult to cross-compile than many packages because much of
+GLib is about hiding differences between different systems.
+
+These notes cover things specific to cross-compiling GLib; for general
+information about cross-compilation, see the [Meson
+documentation](http://mesonbuild.com/Cross-compilation.html).
+
+GLib tries to detect as much information as possible about the target system
+by compiling and linking programs without actually running anything;
+however, some information GLib needs is not available this way. This
+information needs to be provided to meson via a ‘cross file’.
+
+As an example of using a cross file, to cross compile for the ‘MingW32’
+Win64 runtime environment on a Linux system, create a file `cross_file.txt`
+with the following contents:
+
+```
+[host_machine]
+system = 'windows'
+cpu_family = 'x86_64'
+cpu = 'x86_64'
+endian = 'little'
+
+[properties]
+c_args = []
+c_link_args = []
+
+[binaries]
+c = 'x86_64-w64-mingw32-gcc'
+cpp = 'x86_64-w64-mingw32-g++'
+ar = 'x86_64-w64-mingw32-ar'
+ld = 'x86_64-w64-mingw32-ld'
+objcopy = 'x86_64-w64-mingw32-objcopy'
+strip = 'x86_64-w64-mingw32-strip'
+pkgconfig = 'x86_64-w64-mingw32-pkg-config'
+windres = 'x86_64-w64-mingw32-windres'
+```
+
+Then execute the following commands:
+
+    meson setup --cross-file cross_file.txt builddir
+
+The complete list of cross properties follows. Most of these won't need to
+be set in most cases.
+
+## Cross properties
+
+`have_[function]`
+: When meson checks if a function is supported, the test can be overridden by
+  setting the `have_function` property to `true` or `false`. For example:
+
+    Checking for function "fsync" : YES
+
+  can be overridden by setting
+
+    have_fsync = false
+
+`growing_stack=[true/false]`
+: Whether the stack grows up or down. Most places will want `false`. A few
+  architectures, such as PA-RISC need `true`.
+
+`have_strlcpy=[true/false]`
+: Whether you have `strlcpy()` that matches OpenBSD. Defaults to `false`,
+  which is safe, since GLib uses a built-in version in that case.
+
+`va_val_copy=[true/false]`
+: Whether `va_list` can be copied as a pointer. If set to `false`, then
+  `memcopy()` will be used. Only matters if you don't have `va_copy()` or
+  `__va_copy()`. (So, doesn't matter for GCC.) Defaults to `true` which is
+  slightly more common than `false`.
+
+`have_c99_vsnprintf=[true/false]`
+: Whether you have a `vsnprintf()` with C99 semantics. (C99 semantics means
+  returning the number of bytes that would have been written had the output
+  buffer had enough space.) Defaults to `false`.
+
+`have_c99_snprintf=[true/false]`
+: Whether you have a `snprintf()` with C99 semantics. (C99 semantics means
+  returning the number of bytes that would have been written had the output
+  buffer had enough space.) Defaults to `false`.