More documentation improvements

CONTRIBUTING.md

@@ -1,80 +1,4 @@
 # XDG Desktop Portal - Contributing Guide
 
-Before developing features or fixing bugs, please make sure you are have done
-the following:
-
-- Your code is not on the _main_ branch of your fork
-- The code has been tested
-- All commit messages are properly formatted and commits squashed where
-  appropriate
-- You have included updates to all appropriate documentation
-
-We use GitHub pull requests to review contributions. Please be kind and patient
-as code reviews can be long and minutious.
-
-## Development
-
-xdg-desktop-portal usually runs as a user session service, initialized on
-demand through D-Bus activation. It usually starts with the session though,
-as many desktop environments try to talk to xdg-desktop-portal on startup.
-xdg-desktop-portal initializes specific backends through D-Bus activation
-as well.
-
-### Building
-
-To build xdg-desktop-portal, first make sure you have the build dependencies
-installed through your distribution's package manager. With them installed,
-run:
-
-```
-$ meson setup . _build
-$ meson compile -C _build
-```
-
-Some distributions install portal configuration files in `/usr`, while Meson
-defaults to the prefix `/usr/local`. If the portal configuration files in your
-distribution are in `/usr/share/xdg-desktop-portal/portals`, re-configure
-Meson using `meson setup --reconfigure . _build --prefix /usr` and compile
-again.
-
-### Running
-
-xdg-desktop-portal needs to own the D-Bus name and replace the user session
-service that might already be running. To do so, run:
-
-```
-$ _build/src/xdg-desktop-portal --replace
-```
-
-You may need to restart backends after replacing xdg-desktop-portal (please
-replace `[name]` with the backend name, e.g. `gnome` or `kde` or `wlr`):
-
-```
-$ systemctl --user restart xdg-desktop-portal-[name].service
-```
-
-### Testing
-
-To execute the test suite present in xdg-desktop-portal, make sure you built it
-with `-Dlibportal=enabled`, and run:
-
-```
-$ meson test -C _build
-```
-
-### Building the documentation
-
-These instructions are for fedora, where you will need these packages:
-
-```
-sudo dnf install json-glib-devel fuse3-devel gdk-pixbuf2-devel pipewire-devel python3-sphinx flatpak-devel python3-furo python-sphinxext-opengraph python-sphinx-copybutton
-```
-
-Then you can build the website with:
-
-```
-meson setup . _build -Ddocumentation=enabled
-ninja -C _build
-```
-
-Then just load the build website into a browser of your choice from `_build/doc/html/index.html`
+The contribution guidelines have been moved to the online documentation:
+https://flatpak.github.io/xdg-desktop-portal/docs/contributing.html

data/org.freedesktop.impl.portal.Access.xml

@@ -32,7 +32,7 @@
         AccessDialog:
         @handle: Object path to export the Request object at
         @app_id: App id of the application
-        @parent_window: Identifier for the application window, see :ref:`Common Conventions <window-identifiers>`
+        @parent_window: Identifier for the application window, see :doc:`window-identifiers`
         @title: Title for the dialog
         @subtitle: Subtitle for the dialog
         @body: Body text, may be ""

data/org.freedesktop.impl.portal.Account.xml

@@ -33,7 +33,7 @@
         GetUserInformation:
         @handle: Object path for the :ref:`org.freedesktop.portal.Request` object representing this call
         @app_id: App id of the application
-        @window: Identifier for the application window, see :ref:`Common Conventions <window-identifiers>`
+        @window: Identifier for the application window, see :doc:`window-identifiers`
         @options: Vardict with optional further information
         @response: Numeric response
         @results: Vardict with the results of the call

data/org.freedesktop.impl.portal.AppChooser.xml

@@ -33,7 +33,7 @@
         @handle: Object path to export the Request object at
         @app_id: App id of the application
         @title: Title for the app chooser dialog
-        @parent_window: Identifier for the application window, see :ref:`Common Conventions <window-identifiers>`
+        @parent_window: Identifier for the application window, see :doc:`window-identifiers`
         @choices: App ids of applications to let the user choose from
         @options: Vardict with optional further information
         @response: Numeric response

data/org.freedesktop.impl.portal.DynamicLauncher.xml

@@ -30,7 +30,7 @@
         PrepareInstall:
         @handle: Object path for the :ref:`org.freedesktop.impl.portal.Request` object representing this call
         @app_id: App id of the application
-        @parent_window: Identifier for the application window, see :ref:`Common Conventions <window-identifiers>`
+        @parent_window: Identifier for the application window, see :doc:`window-identifiers`
         @name: The default name for the launcher
         @icon_v: A #GBytesIcon as returned by g_icon_serialize()
         @options: Vardict with optional further information

data/org.freedesktop.impl.portal.Email.xml

@@ -30,7 +30,7 @@
         ComposeEmail:
         @handle: Object path for the :ref:`org.freedesktop.impl.portal.Request` object representing this call
         @app_id: App id of the application
-        @parent_window: Identifier for the application window, see :ref:`Common Conventions <window-identifiers>`
+        @parent_window: Identifier for the application window, see :doc:`window-identifiers`
         @options: Vardict with optional further information
         @response: Numeric response
         @results: Vardict with the results of the call

data/org.freedesktop.impl.portal.FileChooser.xml

@@ -35,7 +35,7 @@
         OpenFile:
         @handle: Object path for the :ref:`org.freedesktop.impl.portal.Request` object representing this call
         @app_id: App id of the application
-        @parent_window: Identifier for the application window, see :ref:`Common Conventions <window-identifiers>`
+        @parent_window: Identifier for the application window, see :doc:`window-identifiers`
         @title: Title for the file chooser dialog
         @options: Vardict with optional further information
         @response: Numeric response
@@ -117,7 +117,7 @@
         SaveFile:
         @handle: Object path for the :ref:`org.freedesktop.impl.portal.Request` object representing this call
         @app_id: App id of the application
-        @parent_window: Identifier for the application window, see :ref:`Common Conventions <window-identifiers>`
+        @parent_window: Identifier for the application window, see :doc:`window-identifiers`
         @title: Title for the file chooser dialog
         @options: Vardict with optional further information
         @response: Numeric response
@@ -196,7 +196,7 @@
     </method>
     <!--
       SaveFiles:
-      @parent_window: Identifier for the application window, see :ref:`Common Conventions <window-identifiers>`
+      @parent_window: Identifier for the application window, see :doc:`window-identifiers`
       @title: Title for the file chooser dialog
       @options: Vardict with optional further information
       @handle: Object path for the :ref:`org.freedesktop.portal.Request` object representing this call
@@ -212,13 +212,6 @@
 
       Supported keys in the @options vardict include:
 
-      * ``handle_token`` (``s``)
-
-        A string that will be used as the last element of the
-        @handle. Must be a valid object path element. See the
-        :ref:`org.freedesktop.portal.Request` documentation for more
-        information about the @handle.
-
       * ``accept_label`` (``s``)
 
         Label for the accept button. Mnemonic underlines are allowed.

data/org.freedesktop.impl.portal.GlobalShortcuts.xml

@@ -62,7 +62,7 @@
         @handle: Object path for the :ref:`org.freedesktop.impl.portal.Request` object representing this call
         @session_handle: Object path for the :ref:`org.freedesktop.impl.portal.Session` object representing the session
         @shortcuts: The list of shortcuts to bind. See :ref:`org.freedesktop.portal.GlobalShortcuts.BindShortcuts`
-        @parent_window: Identifier for the application window, see :ref:`Common Conventions <window-identifiers>`
+        @parent_window: Identifier for the application window, see :doc:`window-identifiers`
         @shortcuts: The identifier of the shortcuts we intend to register, empty for all shortcuts
         @results: Vardict with the results of the call
 

data/org.freedesktop.impl.portal.InputCapture.xml

@@ -34,7 +34,7 @@
         @handle: Object path for the :ref:`org.freedesktop.impl.portal.Request` object representing this call
         @session_handle: Object path for the :ref:`org.freedesktop.impl.portal.Session` object representing the session being created
         @app_id: App id of the application
-        @parent_window: Identifier for the application window, see :ref:`Common Conventions <window-identifiers>`
+        @parent_window: Identifier for the application window, see :doc:`window-identifiers`
         @options: Vardict with optional further information
         @response: Numeric response
         @results: Vardict with the results of the call

data/org.freedesktop.impl.portal.Print.xml

@@ -29,7 +29,7 @@
         Print:
         @handle: Object path for the :ref:`org.freedesktop.impl.portal.Request` object representing this call
         @app_id: App id of the application
-        @parent_window: Identifier for the application window, see :ref:`Common Conventions <window-identifiers>`
+        @parent_window: Identifier for the application window, see :doc:`window-identifiers`
         @title: Title for the print dialog
         @fd: File descriptor from which to read the content to print
         @options: Vardict with optional further information
@@ -75,7 +75,7 @@
         PreparePrint:
         @handle: Object path for the :ref:`org.freedesktop.impl.portal.Request` object representing this call
         @app_id: App id of the application
-        @parent_window: Identifier for the application window, see :ref:`Common Conventions <window-identifiers>`
+        @parent_window: Identifier for the application window, see :doc:`window-identifiers`
         @title: Title for the print dialog
         @settings: Serialized print settings
         @page_setup: Serialized page setup

data/org.freedesktop.impl.portal.RemoteDesktop.xml

@@ -119,7 +119,7 @@
         Start:
         @handle: Object path for the :ref:`org.freedesktop.impl.portal.Request` object representing this call
         @app_id: App id of the application
-        @parent_window: Identifier for the application window, see :ref:`Common Conventions <window-identifiers>`
+        @parent_window: Identifier for the application window, see :doc:`window-identifiers`
         @session_handle: Identifier for the remote desktop session
         @parent_window: Identifier for the application window
         @options: Vardict with optional further information

data/org.freedesktop.impl.portal.ScreenCast.xml

@@ -130,7 +130,7 @@
         @handle: Object path for the :ref:`org.freedesktop.impl.portal.Request` object representing this call
         @session_handle: Object path for the :ref:`org.freedesktop.impl.portal.Session` object representing the session
         @app_id: App id of the application
-        @parent_window: Identifier for the application window, see :ref:`Common Conventions <window-identifiers>`
+        @parent_window: Identifier for the application window, see :doc:`window-identifiers`
         @options: Vardict with optional further information
         @response: Numeric response
         @results: Vardict with the results of the call

data/org.freedesktop.impl.portal.Screenshot.xml

@@ -32,7 +32,7 @@
         Screenshot:
         @handle: Object path for the :ref:`org.freedesktop.impl.portal.Request` object representing this call
         @app_id: App id of the application
-        @parent_window: Identifier for the application window, see :ref:`Common Conventions <window-identifiers>`
+        @parent_window: Identifier for the application window, see :doc:`window-identifiers`
         @options: Vardict with optional further information
         @response: Numeric response
         @results: Vardict with the results of the call
@@ -78,7 +78,7 @@
         PickColor:
         @handle: Object path for the :ref:`org.freedesktop.impl.portal.Request` object representing this call
         @app_id: App id of the application
-        @parent_window: Identifier for the application window, see :ref:`Common Conventions <window-identifiers>`
+        @parent_window: Identifier for the application window, see :doc:`window-identifiers`
         @options: Vardict with optional further information
         @response: Numeric response
         @results: Vardict with the results of the call

data/org.freedesktop.impl.portal.Wallpaper.xml

@@ -31,7 +31,7 @@
         SetWallpaperURI:
         @handle: Object path to export the Request object at
         @app_id: App id of the application
-        @parent_window: Identifier for the application window, see :ref:`Common Conventions <window-identifiers>`
+        @parent_window: Identifier for the application window, see :doc:`window-identifiers`
         @uri: The picture file URI
         @options: Options that influence the behavior of the portal
         @response: Numberic response

data/org.freedesktop.portal.Background.xml

@@ -32,7 +32,7 @@
   <interface name="org.freedesktop.portal.Background">
     <!--
         RequestBackground:
-        @parent_window: Identifier for the application window, see :doc:`common-conventions`
+        @parent_window: Identifier for the application window, see :doc:`window-identifiers`
         @options: Vardict with optional further information
         @handle: Object path for the :ref:`org.freedesktop.portal.Request` object representing this call
 

data/org.freedesktop.portal.DynamicLauncher.xml

@@ -95,7 +95,7 @@
     </method>
     <!--
         PrepareInstall:
-        @parent_window: Identifier for the application window, see :doc:`common-conventions`
+        @parent_window: Identifier for the application window, see :doc:`window-identifiers`
         @name: The default name for the launcher
         @icon_v: A ``GBytesIcon`` icon as returned by ``g_icon_serialize()``. Must be a png or jpeg no larger than 512x512, or an svg
         @options: Vardict with optional further information

data/org.freedesktop.portal.Email.xml

@@ -31,7 +31,7 @@
   <interface name="org.freedesktop.portal.Email">
     <!--
         ComposeEmail:
-        @parent_window: Identifier for the application window, see :doc:`common-conventions`
+        @parent_window: Identifier for the application window, see :doc:`window-identifiers`
         @options: Vardict with optional further information
         @handle: Object path for the :ref:`org.freedesktop.portal.Request` object representing this call
 

data/org.freedesktop.portal.FileChooser.xml

@@ -36,7 +36,7 @@
   <interface name="org.freedesktop.portal.FileChooser">
     <!--
       OpenFile:
-      @parent_window: Identifier for the application window, see :doc:`common-conventions`
+      @parent_window: Identifier for the application window, see :doc:`window-identifiers`
       @title: Title for the file chooser dialog
       @options: Vardict with optional further information
       @handle: Object path for the :ref:`org.freedesktop.portal.Request` object representing this call
@@ -156,7 +156,7 @@
     </method>
     <!--
       SaveFile:
-      @parent_window: Identifier for the application window, see :ref:`Common Conventions <window-identifiers>`
+      @parent_window: Identifier for the application window, see :doc:`window-identifiers`
       @title: Title for the file chooser dialog
       @options: Vardict with optional further information
       @handle: Object path for the :ref:`org.freedesktop.portal.Request` object representing this call
@@ -256,7 +256,7 @@
     </method>
     <!--
       SaveFiles:
-      @parent_window: Identifier for the application window, see :ref:`Common Conventions <window-identifiers>`
+      @parent_window: Identifier for the application window, see :doc:`window-identifiers`
       @title: Title for the file chooser dialog
       @options: Vardict with optional further information
       @handle: Object path for the :ref:`org.freedesktop.portal.Request` object representing this call

data/org.freedesktop.portal.GlobalShortcuts.xml

@@ -81,7 +81,7 @@
         BindShortcuts:
         @session_handle: Object path for the :ref:`org.freedesktop.portal.Session` object representing the session
         @shortcuts: The list of shortcuts to bind
-        @parent_window: Identifier for the application window, see :ref:`Common Conventions <window-identifiers>`
+        @parent_window: Identifier for the application window, see :doc:`window-identifiers`
         @options: Vardict with optional further information
         @request_handle: Object path for the :ref:`org.freedesktop.portal.Request` object representing this call
 

data/org.freedesktop.portal.InputCapture.xml

@@ -56,7 +56,7 @@
   <interface name="org.freedesktop.portal.InputCapture">
     <!--
         CreateSession:
-        @parent_window: Identifier for the application window, see :ref:`Common Conventions <window-identifiers>`
+        @parent_window: Identifier for the application window, see :doc:`window-identifiers`
         @options: Vardict with optional further information
         @handle: Object path for the :ref:`org.freedesktop.portal.Request` object representing this call
 

data/org.freedesktop.portal.Location.xml

@@ -74,7 +74,7 @@
     <!--
         Start:
         @session_handle: Object path for the :ref:`org.freedesktop.portal.Session` object
-        @parent_window: Identifier for the application window, see :ref:`Common Conventions <window-identifiers>`
+        @parent_window: Identifier for the application window, see :doc:`window-identifiers`
         @options: Vardict with optional further information
         @handle: Object path for the :ref:`org.freedesktop.portal.Request` object representing this call
 

data/org.freedesktop.portal.OpenURI.xml

@@ -32,7 +32,7 @@
   <interface name="org.freedesktop.portal.OpenURI">
     <!--
         OpenURI:
-        @parent_window: Identifier for the application window, see :ref:`Common Conventions <window-identifiers>`
+        @parent_window: Identifier for the application window, see :doc:`window-identifiers`
         @uri: The uri to open
         @options: Vardict with optional further information
         @handle: Object path for the :ref:`org.freedesktop.portal.Request` object representing this call
@@ -80,7 +80,7 @@
 
     <!--
         OpenFile:
-        @parent_window: Identifier for the application window, see :ref:`Common Conventions <window-identifiers>`
+        @parent_window: Identifier for the application window, see :doc:`window-identifiers`
         @fd: File descriptor for the file to open
         @options: Vardict with optional further information
         @handle: Object path for the :ref:`org.freedesktop.portal.Request` object representing this call
@@ -128,7 +128,7 @@
 
     <!--
         OpenDirectory:
-        @parent_window: Identifier for the application window, see :ref:`Common Conventions <window-identifiers>`
+        @parent_window: Identifier for the application window, see :doc:`window-identifiers`
         @fd: File descriptor for a file
         @options: Vardict with optional further information
         @handle: Object path for the :ref:`org.freedesktop.portal.Request` object representing this call

data/org.freedesktop.portal.Print.xml

@@ -37,7 +37,7 @@
   <interface name="org.freedesktop.portal.Print">
     <!--
         Print:
-        @parent_window: Identifier for the application window, see :ref:`Common Conventions <window-identifiers>`
+        @parent_window: Identifier for the application window, see :doc:`window-identifiers`
         @title: Title for the print dialog
         @fd: File descriptor for reading the content to print
         @options: Vardict with optional further information
@@ -82,7 +82,7 @@
     </method>
     <!--
         PreparePrint:
-        @parent_window: Identifier for the application window, see :ref:`Common Conventions <window-identifiers>`
+        @parent_window: Identifier for the application window, see :doc:`window-identifiers`
         @title: Title for the print dialog
         @settings: Serialized print settings
         @page_setup: Serialized page setup

data/org.freedesktop.portal.RemoteDesktop.xml

@@ -135,7 +135,7 @@
     <!--
         Start:
         @session_handle: Object path for the :ref:`org.freedesktop.portal.Session` object
-        @parent_window: Identifier for the application window, see :ref:`Common Conventions <window-identifiers>`
+        @parent_window: Identifier for the application window, see :doc:`window-identifiers`
         @options: Vardict with optional further information
         @handle: Object path for the :ref:`org.freedesktop.portal.Request` object representing this call