Re: [PATCH] org-protocol.org: updated Linux setup (Gnome) section

[Wilko Meyer]

Thanks for reviewing my patch and adding remarks! I'll attach an updated
version of my patch to this mail based on these.

> It seems, the approach with the .desktop file works for KDE as well
> and even for minimal setup with simple window manager (no real desktop 
> environment). What do you think concerning marking existing sections
> obsolete and adding new universal one for GNU/Linux?

As the XDG Desktop Entry Specification should be a de facto standard
by now, adding a new universal GNU/Linux section seems to be a good
idea. It should work with KDE and other DEs as well (though I have only
tested Mate and Gnome 3 so far).

> Since the entry may appear in UI (menu) I would consider adding
> "Comment" field as well to make it self-descriptive. For the same
> reason I would add "Icon=emacs" (it is unlikely that Org Mode icons
> are available in the system in all necessary sizes). I am unsure if 
> "GenericName" and "Keywords" should be defined and what they may contain.
>
> For additional security I would add "--" separator to avoid treating
> passed argument as an option:
>
>     Exec=emacsclient -- %u
>

These are excellent points. I second that it'll be a good approach to set
expected defaults (such as Icon, Comment, and alike).

GenericName is not required per specification, neither are
Keywords. Keywords seem to be KDE-specific, as it is stated in the
Desktop Entry Specification that those may be prefixed with X-KDE- in
future versions.

> I can not suggest a better category, e.g. Utility is hardly better
> that System, but it is not really a system application as well.

Having considered this I'd advocate to use the "Other" category here.
Utility or System would make sense as well, but as users most likely
won't interact with said .desktop entry via their application menu, it
probably would be beneficial to put it in a more generic place.

> Looking into
> http://git.savannah.gnu.org/cgit/emacs.git/tree/etc/emacsclient.desktop
> I noticed
>
>    StartupWMClass=Emacs
>
> that might give a hint when a new window is created.

Yes, the startup notification spec says:

     > StartupWMClass=STRING
     >    If true, it is KNOWN that the application will map at least one
     >    window with the given string as its WM class or WM name hint.

> When I was setting org-protocol for the first time, I experienced
> various problems. I have seen various recipes, so I think it may be 
> helpful to explicitly state that such commands are obsolete instead of
> removing them completely. The intention is to make users aware that
> such approach should not be tried even if they notice it on some other
> web site. I do not insist though.

I added a sentence stating that formerly mentioned commands may be seen
as obsolote. I'd appreciate feedback/suggestions on how to phrase this
exactly, as I'm not sure if my wording fits.

> Side note: I believe, currently the best setup guide is
> https://github.com/sprig/org-capture-extension/

Agreed. Something I'm unsure of is, wether using the
update-desktop-database command can be seen as universal. It is part of
the package desktop-file-utils in arch linux (emacs has it as a
dependency, so it'll be installed anyways) but I cannot see KDE/plasma
depending on it. I have verified it to be working in a Mate DE, but
wasn't able to verify it using KDE yet. The org-capture guide uses a
different approach than update-desktop-database, so this is something
which should be verified.

> A note unrelated to your patch. With simple "emacsclient %u" handler a
> problem may happen when a browser is started from command line instead 
> of clicking on the icon or from menu. If emacs has no frames then it
> may create a new one in the terminal instead of opening a graphical
> window (Emacs frame). Have you managed to adjust emacs server or
> general buffer settings to ensure new graphical frame (on the same
> virtual desktop) in such cases?

I haven't put much thought into this yet. I ran a quick test by starting
firefox from command line and tried bookmarking a random page via
org-capture. Besides having emacsclient printing some output to STDOUT I
haven't experienced an issues, as the capture frame has been opened in
my running emacs instance. I'll look into this further over this
weekend.

>From 26d34283506cda58ca3e93457ca0d228c40ab3b0 Mon Sep 17 00:00:00 2001
From: Wilko Meyer <w@wmeyer.eu>
Date: Thu, 11 Mar 2022 21:30:45 +0100
Subject: [PATCH] org-protocol.org: updated GNU/Linux setup section

---
 org-contrib/org-protocol.org | 56 +++++++++++++++++++-----------------
 1 file changed, 29 insertions(+), 27 deletions(-)

diff --git a/org-contrib/org-protocol.org b/org-contrib/org-protocol.org
index 57cab17f..935366f7 100644
--- a/org-contrib/org-protocol.org
+++ b/org-contrib/org-protocol.org
@@ -80,41 +80,43 @@ actions. Just register your custom sub-protocol and handler 
with the variable
 
 * Browser / system setup
 
-  - [[Linux setup (Gnome)]]
-  - [[Linux setup (KDE)]]
+  - [[GNU/Linux setup]]
   - [[Windows setup]]
   - [[Mac OS X setup]]
   - [[*Applications][Applications]]
   - [[*Verify the installation][Verify the installation]]
 
-*** Linux setup (Gnome)
-
-    For this to work, you'll need the Gnome-Libraries to be installed.
-
-    : gconftool-2 -s /desktop/gnome/url-handlers/org-protocol/command 
'/usr/local/bin/emacsclient %s' --type String
-    : gconftool-2 -s /desktop/gnome/url-handlers/org-protocol/enabled --type 
Boolean true
-
-*** Linux setup (KDE)
-
-    Add a file =org.protocol= to =~/.kde/share/kde4/services/=:
-
-    #+begin_example
-    # -*- conf -*-
-    [Protocol]
-    protocol=org-protocol
-    exec=/usr/bin/emacsclient '%u'
-    input=none
-    output=none
-    helper=true
-    listing=
-    reading=false
-    writing=false
-    makedir=false
-    deleting=false
+*** GNU/Linux setup
+
+    Most more common desktop environments (Gnome, KDE et al) comply with the 
[[https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html][XDG
 Desktop Entry Specification]].
+    This means setting up =emacsclient= as the =org-protocol= handler using a 
.desktop file can be regarded
+    as a, in most cases, standard way to set this up in most common desktop 
environments.
+
+    Some environments, e.g. Gnome as of Gnome 3, have deprecated other 
configuration methods,
+    e.g. =gconftool-2= to set-up protocol handling.
+    
+    Create a =org-protocol.desktop= file either in 
=~/.local/share/applications/= to set-up =emacsclient= as the
+    =org-protocol= handler for the current user or in 
=/usr/share/applications= to set-up a system-wide
+    configuration:
+
+    #+begin_example    
+    [Desktop Entry]
+    Name=org-protocol
+    Comment= Intercept calls from emacsclient to trigger custom actions
+    Categories=Other;
+    Keywords=org-protocol;
     Icon=emacs
-    Description=A protocol for org-mode
+    Type=Application
+    Exec=emacsclient -- %u
+    Terminal=false
+    StartupWMClass=Emacs
+    MimeType=x-scheme-handler/org-protocol;
     #+end_example
 
+    Update the cache database of MIME types handled by desktop files via:
+
+    : update-desktop-database ~/.local/share/applications/
+
 *** Windows setup
 
     Windows users may register the "=org-protocol=" once for all by adjusting 
the
-- 
2.35.1