Some updates

docs/building-introduction.rst

@@ -21,7 +21,8 @@ at the same time, which get bundled into the build.
 
 It is packaged by several distributions and there is also a
 `Flatpak package <https://flathub.org/apps/org.flatpak.Builder>`_ called
-``org.flatpak.Builder`` available for it on Flathub.
+``org.flatpak.Builder`` available for it on Flathub (this may contain
+Flathub specific downstream modifications).
 
 The input to ``flatpak-builder`` is a manifest file. This specifies the
 parameters for the application that will be built, such as its name and

docs/extension.rst

@@ -26,6 +26,11 @@ manifest.
 not need to be specified manually. These are automaitcally created and
 loaded if installed.
 
+Note that, ``.Locale`` extensions are by default only partially
+installed (only for the configued languages) by Flatpak. To install the
+full locale extension ``flatpak update --subpath= $FLATPAK_ID.Locale``
+can be used.
+
 Extension point
 ---------------
 
@@ -190,6 +195,15 @@ enable-if.
 to ``false`` the extension will be considered unused and removed
 automatically when doing ``flatpak uninstall --unused``.
 
+Extensions are automatically mounted inside the runtime or app sandbox
+provided the correct branch of the extension is installed, the
+extension point for that extension is specified in the app or runtime
+manifest and all the conditionals in the extension point match.
+
+The list of loaded extensions can be found by inspecting the
+``app-extensions`` and ``runtime-extensions`` keys of the ``Instance``
+group in ``/.flatpak-info`` of a running Flatpak.
+
 Loading existing extensions
 ---------------------------
 

docs/first-build.rst

@@ -16,7 +16,7 @@ popular distributions.
 
 Please also install ``flatpak-builder`` from your distribution. There is
 also a flatpak-builder `Flatpak package <https://flathub.org/apps/org.flatpak.Builder>`_
-on Flathub.
+on Flathub (this may contain Flathub specific downstream modifications).
 
 Then install the Flathub repository `userwide`::
 

docs/flatpak-builder.rst

@@ -4,7 +4,7 @@ Flatpak Builder
 ``flatpak-builder`` has already been introduced in :doc:`first-build`
 and :doc:`building-introduction`. It is packaged by most of the popular
 distributions and there is also a flatpak-builder `Flatpak package <https://flathub.org/apps/org.flatpak.Builder>`_
-on Flathub.
+on Flathub (this may contain Flathub specific downstream modifications).
 
 This page provides additional details on how to use ``flatpak-builder``,
 including the various command options that are available.

docs/sandbox-permissions.rst

@@ -77,18 +77,28 @@ which can be used on an as-needed basis, and which should be avoided.
 Standard permissions
 ````````````````````
 
-The following permissions provide access to basic resources that applications
-commonly require, and can therefore be freely used.
+The following permissions are commonly used by applications.
 
 - ``--allow=bluetooth`` - Allow access to Bluetooth (``AF_BLUETOOTH``) sockets
 - ``--device=dri`` - OpenGL rendering
 - ``--share=ipc`` - Share IPC namespace with the host [#f1]_
 - ``--share=network`` - Access the network [#f2]_
-- ``--socket=cups`` - Talk to the CUPS printing system (``$CUPS_SERVER`` or server defined in CUPS's ``client.conf``. Falls back to ``/var/run/cups/cups.sock``)
-- ``--socket=gpg-agent`` - Talk to the GPG agent (The socket in ``gpgconf --list-dir agent-socket``)
-- ``--socket=pcsc`` - Smart card access ``$PCSCLITE_CSOCK_NAME``
-- ``--socket=pulseaudio`` - Access to PulseAudio, includes sound input (mic), sound output/playback, MIDI and ALSA sound devices in ``/dev/snd``
-- ``--socket=ssh-auth``- Allow access to ``$SSH_AUTH_SOCK``
+- ``--socket=pulseaudio`` - Access to PulseAudio. It includes sound input
+  (mic), sound output/playback, MIDI and ALSA sound devices in
+  ``/dev/snd``. This permission can be sensitive in certain situations.
+- ``--socket=cups`` - Talk to the CUPS printing system. ``$CUPS_SERVER``
+  or server defined in CUPS's ``client.conf``. Falls back to
+  ``/var/run/cups/cups.sock``.
+- ``--socket=pcsc`` - Smart card access ``$PCSCLITE_CSOCK_NAME``.
+- ``--socket=gpg-agent`` - Talk to the GPG agent running on host. This
+  may allow acquiring additional permissions that can be used to perform
+  priviledged GPG operations. The gives access to the socket in
+  ``gpgconf --list-dir agent-socket``. This is not commonly needed
+  unless the application interacts with GPG such as e-mail clients or
+  GPG frontends.
+- ``--socket=ssh-auth``- Allow access to ``$SSH_AUTH_SOCK``. This is not
+  commonly needed unless the application interacts with SSH such as
+  Git clients or SSH frontends.
 
 .. note::
 

po/de/LC_MESSAGES/building-introduction.po

@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version:  Flatpak\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2025-02-12 09:37+0530\n"
+"POT-Creation-Date: 2025-08-31 14:40+0530\n"
 "PO-Revision-Date: 2019-06-26 05:15-0400\n"
 "Last-Translator: Markus Richter <semanticdesign@pm.me>\n"
 "Language: de\n"
@@ -62,10 +62,11 @@ msgstr ""
 msgid ""
 "It is packaged by several distributions and there is also a `Flatpak "
 "package <https://flathub.org/apps/org.flatpak.Builder>`_ called "
-"``org.flatpak.Builder`` available for it on Flathub."
+"``org.flatpak.Builder`` available for it on Flathub (this may contain "
+"Flathub specific downstream modifications)."
 msgstr ""
 
-#: ../../building-introduction.rst:26
+#: ../../building-introduction.rst:27
 msgid ""
 "The input to ``flatpak-builder`` is a manifest file. This specifies the "
 "parameters for the application that will be built, such as its name and "
@@ -85,13 +86,13 @@ msgstr ""
 "Eines der Module (gewöhnlich das Letzte) ist der Programmcode der "
 "Anwendung selbst."
 
-#: ../../building-introduction.rst:34
+#: ../../building-introduction.rst:35
 msgid "The basic format used to invoke ``flatpak-builder`` is::"
 msgstr ""
 "Das zugrundeliegende Format für den Aufruf von ``flatpak-builder`` sieht "
 "so aus::"
 
-#: ../../building-introduction.rst:38
+#: ../../building-introduction.rst:39
 msgid ""
 "Where ``<build-dir>`` is the path to the directory that the application "
 "will be built into, and ``<manifest>`` is the path to a manifest file. "
@@ -103,48 +104,48 @@ msgstr ""
 "Der Inhalt von ``<build-dir>`` kann zum Testen und Debuggen nützlich "
 "sein, wird aber generell als Artefakt des Build-Prozesses behandelt."
 
-#: ../../building-introduction.rst:43
+#: ../../building-introduction.rst:44
 msgid "When ``flatpak-builder`` is run:"
 msgstr "Das Ausführen von ``flatpak-builder`` setzt folgende Prozesse in Gang::"
 
-#: ../../building-introduction.rst:45
+#: ../../building-introduction.rst:46
 msgid "The build directory is created, if it doesn't already exist"
 msgstr "Das Build-Verzeichnis wird erzeugt, sofern es noch nicht existiert."
 
-#: ../../building-introduction.rst:46
+#: ../../building-introduction.rst:47
 msgid "The source code for each module is downloaded and verified"
 msgstr "Der Quellcode wird für jedes Modul heruntergeladen und verifiziert."
 
-#: ../../building-introduction.rst:47
+#: ../../building-introduction.rst:48
 msgid "The source code for each module is built and installed"
 msgstr "Der Quellcode wird für jedes Modul kompiliert und installiert."
 
-#: ../../building-introduction.rst:48
+#: ../../building-introduction.rst:49
 #, fuzzy
 msgid "The build is finished by setting sandbox permissions"
 msgstr ""
 "Der Erstellungsvorgang wird mit dem Setzen der Sandbox-Berechtigungen "
 "abgeschlossen."
 
-#: ../../building-introduction.rst:49
+#: ../../building-introduction.rst:50
 msgid ""
 "The build result is exported to a repository (which will be created if it"
 " doesn't exist already)"
 msgstr ""
 "Das Resultat des Erstellungsprozesses wird zu einem Repository exportiert"
 " (welches erzeugt wird, wenn es nicht bereits existiert)."
 
-#: ../../building-introduction.rst:52
+#: ../../building-introduction.rst:53
 msgid "The application can then be installed from the repository and run."
 msgstr ""
 "Die Anwendung kann vom Repository aus installiert und anschließend "
 "gestartet werden."
 
-#: ../../building-introduction.rst:55
+#: ../../building-introduction.rst:56
 msgid "Software Development Kits (SDKs)"
 msgstr "Software Development Kits (SDKs)"
 
-#: ../../building-introduction.rst:57
+#: ../../building-introduction.rst:58
 msgid ""
 "Instead of being built using the host environment, Flatpak applications "
 "are built inside a separate environment, called an SDK."
@@ -153,7 +154,7 @@ msgstr ""
 "dessen werden Flatpak-Anwendungen innerhalb einer separaten Umgebung "
 "erzeugt, dem SDK."
 
-#: ../../building-introduction.rst:60
+#: ../../building-introduction.rst:61
 msgid ""
 "SDKs are like the regular runtime that applications run in. The "
 "difference is that SDKs also include all the development resources and "
@@ -166,7 +167,7 @@ msgstr ""
 "zu erzeugen, sowie Tools für die Erstellung und Paketierung, Header-"
 "Dateien, Compiler und Debugger."
 
-#: ../../building-introduction.rst:65
+#: ../../building-introduction.rst:66
 #, fuzzy
 msgid ""
 "Each runtime has an accompanying SDK. For example, there is both a GNOME "
@@ -178,7 +179,7 @@ msgstr ""
 "3.26 SDK. Anwendungen, die diese Laufzeitumgebung verwenden, werden mit "
 "dem zugehörigen SDK erstellt."
 
-#: ../../building-introduction.rst:69
+#: ../../building-introduction.rst:70
 #, fuzzy
 msgid ""
 "Like runtimes, SDKs will sometimes be automatically installed for you, "
@@ -215,3 +216,11 @@ msgstr ""
 #~ "for details."
 #~ msgstr ""
 
+#~ msgid ""
+#~ "It is packaged by several distributions"
+#~ " and there is also a `Flatpak "
+#~ "package <https://flathub.org/apps/org.flatpak.Builder>`_ "
+#~ "called ``org.flatpak.Builder`` available for "
+#~ "it on Flathub."
+#~ msgstr ""
+