config/graphical-session/portals.md: document portal setup

seems a lot of people have had issues with this, sometimes exacerbated by the
recent portals.conf change. Others have issues because they only install
`-wlr`, which doesn't provide many of the common interfaces.

src/SUMMARY.md

@@ -53,6 +53,7 @@
       - [Wayland](./config/graphical-session/wayland.md)
       - [Fonts](./config/graphical-session/fonts.md)
       - [Icons](./config/graphical-session/icons.md)
+      - [XDG Desktop Portals](./config/graphical-session/portals.md)
       - [GNOME](./config/graphical-session/gnome.md)
       - [KDE](./config/graphical-session/kde.md)
    - [Multimedia](./config/media/index.md)

src/config/external-applications.md

@@ -58,8 +58,8 @@ security and/or privacy-violating features of proprietary software.
 
 Some apps may not function properly (e.g. not being able to access the host
 system's files). Some of these issues can be fixed by installing one or more of
-the `xdg-desktop-portal`, `xdg-desktop-portal-gtk`, `xdg-user-dirs`,
-`xdg-user-dirs-gtk` or `xdg-utils` packages.
+the `xdg-user-dirs`, `xdg-user-dirs-gtk` or `xdg-utils` packages, and setting up
+[XDG Desktop Portals](./graphical-session/portals.md).
 
 Some Flatpaks require [D-Bus](./session-management.md#d-bus) and/or
 [Pulseaudio](./media/pulseaudio.md).

src/config/graphical-session/portals.md

@@ -0,0 +1,32 @@
+# XDG Desktop Portals
+
+Some applications, including [Flatpak](../external-applications.md#flatpak), use
+[XDG Desktop Portals](https://github.com/flatpak/xdg-desktop-portal) to provide
+access to various system interfaces, including file open and save dialogs, the
+clipboard, screencasting, opening URLs, and more.
+
+## Installation
+
+XDG Desktop Portals require a [user D-Bus session
+bus](../session-management.md#d-bus). Install `xdg-desktop-portal` and one or
+more backends:
+
+| Backend                    | Notes                                                                          |
+|----------------------------|--------------------------------------------------------------------------------|
+| `xdg-desktop-portal-gnome` | Provides most common and GNOME-specific interfaces (GTK+ UI)                   |
+| `xdg-desktop-portal-gtk`   | Provides most common interfaces (GTK+ UI)                                      |
+| `xdg-desktop-portal-kde`   | Provides most common and KDE-specific interfaces (Qt/KF5 UI)                   |
+| `xdg-desktop-portal-lxqt`  | Only provides a file chooser (based on libfm-qt)                               |
+| `io.elementary.files`      | Only provides a file chooser                                                   |
+| `xdg-desktop-portal-wlr`   | Only provides a screenshot and screencasting interface for wlroots compositors |
+
+If unsure what to choose, `xdg-desktop-portal-gtk` is a good default choice.
+
+## Configuration
+
+In most cases, the default configuration, located at
+`/usr/share/xdg-desktop-portal/portals.conf`, should suffice. If necessary, this
+configuration can be overridden for specific desktop environments and portal
+interfaces by creating `$XDG_CURRENT_DESKTOP-portals.conf` or `portals.conf` at
+the system or user level as described in
+[portals.conf(5)](https://man.voidlinux.org/portals.conf.5).