From 907d7f26df777525b5db4f34ee5fcf229a3d058a Mon Sep 17 00:00:00 2001
From: Robin Candau <robincandau@protonmail.com>
Date: Sun, 19 May 2024 20:47:46 +0200
Subject: [PATCH] Add the method to force `arch-update` to run in a specific
 terminal emulator via the desktop file to the documentation (#168)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Add the method to force `arch-update` to run in a specific terminal emulator via the desktop file to the documentation (as a workaround for people using a terminal emulator not supported by `gio` for whom clicking on the systray applet icon does nothing)

This PR aims to add the method required to force `arch-update` to run in a specific terminal emulator via the desktop file to the documentation.
This is to document this as workaround for people using a terminal emulator not [known/supported](https://gitlab.gnome.org/GNOME/glib/-/blob/main/gio/gdesktopappinfo.c#L2694) by `gio` (for whom cliking on the systray applet icon does nothing and reports the following error: `gio: Unable to launch application ‘/usr/share/applications/arch-update.desktop’: Unable to find terminal required for application`).

It also includes some alternatives, such as creating a symlink pointing to `/usr/bin/xterm` for the desired terminal emulator, or simply installing a supported terminal emulator.

Fixes https://github.com/Antiz96/arch-update/issues/162
---
 README-fr.md             | 18 ++++++++++++++++++
 README.md                | 18 ++++++++++++++++++
 doc/man/arch-update.1    | 24 ++++++++++++++++++++++++
 doc/man/fr/arch-update.1 | 24 ++++++++++++++++++++++++
 4 files changed, 84 insertions(+)

diff --git a/README-fr.md b/README-fr.md
index 666a455..927c040 100644
--- a/README-fr.md
+++ b/README-fr.md
@@ -96,6 +96,9 @@ L'applet systray essaie de lire le fichier `arch-update.desktop` dans les chemin
 
 Dans le cas où vous avez envie/besoin de personnaliser le fichier `arch-update.desktop`, copiez le dans un chemin qui a une priorité plus élevée que le chemin d'installation par défaut et modifier le ici (afin d'assurer que votre ficher `arch-update.desktop` personnalisé remplace celui par défaut et que vos modifications ne soient pas écrasées à chaque mise à jour).
 
+Cela peut être utile pour forcer le fichier `arch-update.desktop` à lancer `Arch-Update` avec un émulateur de terminal spécifique par exemple.  
+**Si cliquer sur l'applet systray ne fait rien**, veuillez lire [ce chapitre](#forcer-le-fichier-desktop-à-se-lancer-avec-un-émulateur-de-terminal-spécifique).
+
 ### Le timer systemd
 
 Il existe un service systemd (sous `/usr/lib/systemd/user/arch-update.service` ou `/usr/local/lib/systemd/user/arch-update.service` si vous avez installé `Arch-Update` [depuis la source](#depuis-la-source)) qui exécute la fonction `check` quand il est démarré (voir le chapitre [Documentation](#documentation)).  
@@ -237,6 +240,21 @@ Voir <https://www.freedesktop.org/software/systemd/man/latest/systemd.time.html#
 
 Dans le cas où vous voulez qu'`Arch-Update` ne vérifie les nouvelles mises à jour qu'une fois au démarrage du système, vous pouvez simplement supprimer la ligne `OnUnitActiveSec` complètement.
 
+### Forcer le fichier desktop à se lancer avec un émulateur de terminal spécifique
+
+`gio` (qui est utilisé pour lancer le fichier `arch-update.desktop` quand l'applet systray est cliquée) ne supporte actuellement qu'une [liste limitée d'émulateurs de terminal](https://gitlab.gnome.org/GNOME/glib/-/blob/main/gio/gdesktopappinfo.c#L2694).  
+Si vous n'avez aucun de ces émulateurs de terminal installé sur votre système, il se peut que vous soyez confronté à un problème où cliquer sur l'applet systray [ne fait rien](https://github.com/Antiz96/arch-update/issues/162) et rapporte l'erreur suivante : `[...] Unable to find terminal required for application`.
+
+En attendant que Gnome implémente une méthode permettant aux utilisateurs d'utiliser l'émulateur de terminal de leur choix avec `gio` (ce qui, espérons-le, [arrivera à un moment ou à un autre](https://gitlab.freedesktop.org/terminal-wg/specifications/-/merge_requests/3)), vous pouvez contourner le problème en copiant le fichier `arch-update.desktop` dans `$HOME/.local/share/applications/arch-update.desktop` (par exemple, voir [ce chapitre](#lapplet-systray) pour plus de détails) et en modifiant la ligne `Exec` pour "forcer" `arch-update` à s'exécuter dans l'émulateur de terminal de votre choix.  
+Par exemple, avec [alacritty](https://alacritty.org/) *(vérifier le manuel de votre émulateur de terminal pour trouver la bonne option à utiliser)* :
+
+```text
+[...]
+Exec=alacritty -e arch-update
+```
+
+Alternativement, vous pouvez créer un lien symbolique de votre émulateur de terminal pointant vers `/usr/bin/xterm`, qui est l'option de "secours" pour `gio` (par exemple, avec [alacritty](https://alacritty.org) : `sudo ln -s /usr/bin/alacritty /usr/bin/xterm`) ou vous pouvez simplement installer un des émulateurs de terminal [connus/supportés](https://gitlab.gnome.org/GNOME/glib/-/blob/main/gio/gdesktopappinfo.c#L2694) par `gio`.
+
 ## Contribuer
 
 Vous pouvez soulever vos problèmes, commentaires et suggestions dans l'onglet [Issues](https://github.com/Antiz96/arch-update/issues).  
diff --git a/README.md b/README.md
index a94a420..116ea35 100644
--- a/README.md
+++ b/README.md
@@ -96,6 +96,9 @@ The systray applet attempts to read the `arch-update.desktop` file at the below
 
 In case you want/need to customize the `arch-update.desktop` file, copy it in a path that has a higher priority than the default installation path and modify it there (to ensure that your custom `arch-update.desktop` file supersedes the default one and that your modifications are not being overwritten on updates).
 
+This can be useful to force the `arch-update.desktop` file to launch `Arch-Update` with a specific terminal emulator for instance.  
+**If clicking the systray applet does nothing**, please read [this chapter](#force-the-desktop-file-to-run-with-a-specific-terminal-emulator).
+
 ### The systemd timer
 
 There is a systemd service (in `/usr/lib/systemd/user/arch-update.service` or in `/usr/local/lib/systemd/user/arch-update.service` if you installed `Arch-Update` [from source](#from-source)) that executes the `check` function when started (see the [Documentation](#documentation) chapter).  
@@ -237,6 +240,21 @@ See <https://www.freedesktop.org/software/systemd/man/latest/systemd.time.html#P
 
 In case you want `Arch-Update` to check for new updates only once at boot, you can simply delete the `OnUnitActiveSec` line completely.
 
+### Force the desktop file to run with a specific terminal emulator
+
+`gio` (which is used to launch the `arch-update.desktop` file when the systray applet is clicked) currently supports a [limited list of terminal emulators](https://gitlab.gnome.org/GNOME/glib/-/blob/main/gio/gdesktopappinfo.c#L2694).  
+If you don't have any of these terminal emulators installed on your system, you might face an issue where clicking the systray applet [does nothing](https://github.com/Antiz96/arch-update/issues/162) and reports the following error: `[...] Unable to find terminal required for application`.
+
+While waiting for Gnome to implement a way to allow people using their terminal emulator of choice with `gio` (which will hopefully [happen at some point](https://gitlab.freedesktop.org/terminal-wg/specifications/-/merge_requests/3)), you can workaround this issue by copying the `arch-update.desktop` file to `$HOME/.local/share/applications/arch-update.desktop` (for instance, see [this chapter](#the-systray-applet) for more details) and modifying the `Exec` line in it to "force" `arch-update` to run with your terminal emulator of choice.  
+For instance, with [alacritty](https://alacritty.org/) *(check your terminal emulator's manual to find the correct option to use)*:
+
+```text
+[...]
+Exec=alacritty -e arch-update
+```
+
+Alternatively, you can create a symlink for your terminal emulator that points to `/usr/bin/xterm`, which is the fallback option for `gio` (for instance, with [alacritty](https://alacritty.org): `sudo ln -s /usr/bin/alacritty /usr/bin/xterm`) or you can simply install one of the terminal emulators [known/supported](https://gitlab.gnome.org/GNOME/glib/-/blob/main/gio/gdesktopappinfo.c#L2694) by `gio`.
+
 ## Contributing
 
 You can raise your issues, feedbacks and suggestions in the [issues tab](https://github.com/Antiz96/arch-update/issues).  
diff --git a/doc/man/arch-update.1 b/doc/man/arch-update.1
index 985c2f4..b4d49b1 100644
--- a/doc/man/arch-update.1
+++ b/doc/man/arch-update.1
@@ -96,6 +96,11 @@ Display the help message.
 
 .RB "In case you want/need to customize the " "arch-update.desktop " "file, copy it in a path that has a higher priority than the default installation path and modify it there (to ensure that your custom " "arch-update.desktop " "file supersedes the default one and that your modifications are not being overwritten on updates)."
 
+.br
+.RB "This can be useful to force the " "arch-update.desktop " "file to launch " "Arch-Update " "within a specific terminal emulator for instance."
+.br
+.BR "If clicking the systray applet does nothing" ", please read the " "'Force the desktop file to run with a specific terminal emulator' " "chapter in the " "Tips and Tricks " "section below."
+
 .TP
 .B The systemd timer
 .RB "There is a systemd service in " "/usr/lib/systemd/user/arch-update.service " "(or in " "/etc/systemd/user/arch-update.service " "if you installed arch-update from source) that executes the " "\-\-check " "function when launched. To launch it automatically " "at boot and then once every hour " "enable the associated systemd timer (the auto-check cycle can be modified to your liking. See the TIPS AND TRICKS chapter below):"
@@ -150,6 +155,25 @@ See https://www.freedesktop.org/software/systemd/man/latest/systemd.time.html#Pa
 
 .RB "In case you want " "Arch-Update " "to check for new updates only once at boot, you can simple delete the " "OnUnitActiveSec " "line completely."
 
+.TP
+.B Force the desktop file to run with a specific terminal emulator
+.BR "gio " "(which is used to launch the " "arch-update.desktop " "file when the systray applet is clicked) currently supports a limited list of terminal emulators (see https://gitlab.gnome.org/GNOME/glib/-/blob/main/gio/gdesktopappinfo.c#L2694).
+.br
+.RB "If you don't have any of these terminal emulators installed on your system, you might face an issue where clicking the systray applet does nothing and reports the following error: " "[...] Unable to find terminal required for application".
+
+.br
+.RB "While waiting for Gnome to implement a way to allow people using their terminal emulator of choice with " "gio" ", you can workaround this issue by copying the " "arch-update.desktop " "file to " "$HOME/.local/share/applications/arch-update.desktop " "(for instance, see " "'The systray applet' " "chapter for more details) and modifying the " "Exec " "line in it to 'force' " "arch-update " "to run with your terminal emulator of choice."
+.br
+.RB "For instance, with " "alacritty " "(check your terminal emulator's manual to find the correct option to use):"
+
+.br
+[...]
+.br
+.RB "Exec=" "alacritty -e " "arch-update"
+
+.br
+.RB "Alternatively, you can create a symlink for your terminal emulator that points to " "/usr/bin/xterm" ", which is the fallback option for " "gio " "(for instance, with " "alacritty" ": " "sudo ln -s /usr/bin/alacritty /usr/bin/xterm" ") or you can simply install one of the terminal emulators known/supported by " "gio " "(see https://gitlab.gnome.org/GNOME/glib/-/blob/main/gio/gdesktopappinfo.c#L2694)."
+
 .SH EXIT STATUS
 .TP
 .B 0
diff --git a/doc/man/fr/arch-update.1 b/doc/man/fr/arch-update.1
index 2d928a5..cdc5d63 100644
--- a/doc/man/fr/arch-update.1
+++ b/doc/man/fr/arch-update.1
@@ -96,6 +96,11 @@ Afficher le message d'aide.
 
 .RB "Dans le cas où vous avez envie/besoin de personnaliser le fichier " "arch-update.desktop" ", copiez le dans un chemin qui a une priorité plus élevée que le chemin d'installation par défaut et modifier le ici (afin d'assurer que votre ficher " "arch-update.desktop " "personnalisé remplace celui par défaut et que vos modifications ne soient pas écrasées à chaque mise à jour)."
 
+.br
+.RB "Cela peut être utile pour forcer le fichier " "arch-update.desktop " "à lancer " "Arch-Update " "dans un émulateur de terminal spécifique par exemple."
+.br
+.BR "Si cliquer sur l'applet systray ne fait rien" ", veuillez lire le chapitre " "'Forcer le fichier desktop à se lancer avec un émulateur de terminal spécifique' " "dans la section " "Trucs et Astuces " "ci-dessous."
+
 .TP
 .B Le timer systemd
 .RB "Il existe un service systemd dans " "/usr/lib/systemd/user/arch-update.service " "(ou dans " "/etc/systemd/user/arch-update.service " "si vous avez installé arch-update depuis la source) qui exécute la fonction " "\-\-check " "quand il est démarré. Pour le démarrer automatiquement " "au démarrage du système puis une fois toutes les heures, " "activez le timer systemd associé (vous pouvez modifier le cycle de vérification automatique à votre guise, voir le chapitre TRUCS ET ASTUCES ci-dessous) :"
@@ -150,6 +155,25 @@ Voir https://www.freedesktop.org/software/systemd/man/latest/systemd.time.html#P
 
 .RB "Dans le cas où vous voulez qu'" "Arch-Update " "ne vérifie les nouvelles mises à jour qu'une fois au démarrage du système, vous pouvez simplement supprimer la ligne " "OnUnitActiveSec " "complètement."
 
+.TP
+.B Forcer le fichier desktop à se lancer avec un émulateur de terminal spécifique
+.BR "gio " "(qui est utilisé pour lancer le fichier " "arch-update.desktop " "quand l'applet systray est cliquée) ne supporte actuellement qu'une liste limitée d'émulateurs de terminal (voir https://gitlab.gnome.org/GNOME/glib/-/blob/main/gio/gdesktopappinfo.c#L2694)."
+.br
+.RB "Si vous n'avez aucun de ces émulateurs de terminal installé sur votre système, il se peut que vous soyez confronté à un problème où cliquer sur l'applet systray ne fait rien et rapporte l'erreur suivante : " "[...] Unable to find terminal required for application".
+
+.br
+.RB "En attendant que Gnome implémente une méthode permettant aux utilisateurs d'utiliser l'émulateur de terminal de leur choix avec " "gio" ",vous pouvez contourner le problème en copiant le fichier " "arch-update.desktop " "dans " "$HOME/.local/share/applications/arch-update.desktop " "(par exemple, voir le chapitre " "'L'applet systray' "  "pour plus de détails) et en modifiant la ligne " "Exec " "pour 'forcer' " "arch-update " "à s'exécuter dans l'émulateur de terminal de votre choix."
+.br
+.RB "Par exmeple, avec " "alacritty " "(vérifier le manuel de votre émulateur de terminal pour trouver la bonne option à utiliser) :"
+
+.br
+[...]
+.br
+.RB "Exec=" "alacritty -e " "arch-update"
+
+.br
+.RB "Alternativement, vous pouvez créer un lien symbolique de votre émulateur de terminal pointant vers " "/usr/bin/xterm" ", qui est l'option de 'secours' pour " "gio " "(par exemple, avec " "alacritty" ": " "sudo ln -s /usr/bin/alacritty /usr/bin/xterm" ") ou vous pouvez simplement installer un des émulateurs de terminal connus/supportés par " "gio " "(voir https://gitlab.gnome.org/GNOME/glib/-/blob/main/gio/gdesktopappinfo.c#L2694)."
+
 .SH EXIT STATUS
 .TP
 .B 0