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

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

[Wilko Meyer]

[-- Attachment #1: Type: text/plain, Size: 347 bytes --]

Good evening,

I'd like to suggest an update to the org-protocol.org "Linux setup (Gnome)"
section as it is refering to gconf/gconftool-2 which is deprecated as of
Gnome 3. It may be a good idea to use .desktop-Files (as described in
freedesktop.orgs Desktop Entry/Menu Specification) here to complete this
step (which is what my patch suggests).

[-- Attachment #2: 0001-org-protocol.org-updated-Linux-setup-Gnome-section-a.patch --]
[-- Type: text/plain, Size: 1414 bytes --]

From 8c62f173c34929dd03e324ff3ec4d457850e52c4 Mon Sep 17 00:00:00 2001
From: Wilko Meyer <w@wmeyer.eu>
Date: Thu, 10 Mar 2022 19:59:45 +0100
Subject: [PATCH] org-protocol.org: updated Linux setup (Gnome) section as
 gconf is deprecated by now

---
 org-contrib/org-protocol.org | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/org-contrib/org-protocol.org b/org-contrib/org-protocol.org
index 57cab17f..b10ef41e 100644
--- a/org-contrib/org-protocol.org
+++ b/org-contrib/org-protocol.org
@@ -89,10 +89,21 @@ actions. Just register your custom sub-protocol and handler with the variable
 
 *** Linux setup (Gnome)
 
-    For this to work, you'll need the Gnome-Libraries to be installed.
+    Add a file =org-protocol.desktop= to =~/.local/share/applications/=:
+
+    #+begin_example    
+    [Desktop Entry]
+    Name=org-protocol
+    Exec=emacsclient '%u'
+    Type=Application
+    Terminal=false
+    Categories=System;
+    MimeType=x-scheme-handler/org-protocol;
+    #+end_example
+
+    Update the cache database of MIME types handled by desktop files via:
 
-    : 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
+    : update-desktop-database ~/.local/share/applications/
 
 *** Linux setup (KDE)
 
-- 
2.35.1

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

[Max Nikulin]

On 11/03/2022 02:35, Wilko Meyer wrote:
> 
> I'd like to suggest an update to the org-protocol.org "Linux setup (Gnome)"
> section as it is refering to gconf/gconftool-2 which is deprecated as of
> Gnome 3. It may be a good idea to use .desktop-Files (as described in
> freedesktop.orgs Desktop Entry/Menu Specification) here to complete this
> step (which is what my patch suggests).

Greet, definitely this page is severely outdated. I have a little 
experience with .desktop files so do not hesitate to object to my comments.

> diff --git a/org-contrib/org-protocol.org b/org-contrib/org-protocol.org
> index 57cab17f..b10ef41e 100644
> --- a/org-contrib/org-protocol.org
> +++ b/org-contrib/org-protocol.org
> @@ -89,10 +89,21 @@ actions. Just register your custom sub-protocol and handler with the variable
>  
>  *** Linux setup (Gnome)
                    ^^^^^^^
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?

> -    For this to work, you'll need the Gnome-Libraries to be installed.
> +    Add a file =org-protocol.desktop= to =~/.local/share/applications/=:
> +
> +    #+begin_example    
> +    [Desktop Entry]
> +    Name=org-protocol

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.

> +    Exec=emacsclient '%u'

Accordingly to "Desktop Entry Specification"
https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html

> Field codes must not be used inside a quoted argument, the result of
> field code expansion inside a quoted argument is undefined. The %F and
> %U field codes may only be used as an argument on their own.

For additional security I would add "--" separator to avoid treating 
passed argument as an option:

     Exec=emacsclient -- %u

> +    Type=Application
> +    Terminal=false
> +    Categories=System;

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.

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.

> +    MimeType=x-scheme-handler/org-protocol;
> +    #+end_example
> +
> +    Update the cache database of MIME types handled by desktop files via:
>  
> -    : 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

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.

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

> +    : update-desktop-database ~/.local/share/applications/
>  
>  *** Linux setup (KDE)

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?

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

[Wilko Meyer]

[-- Attachment #1: Type: text/plain, Size: 4288 bytes --]


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.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: [PATCH] org-protocol.org --]
[-- Type: text/x-patch, Size: 3022 bytes --]

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

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

[Max Nikulin]

Applied

...with some minor tweaks (let me know if you do not like them). Thank you.

https://orgmode.org/worg/org-contrib/org-protocol.html has been updated.

On 12/03/2022 02:37, Wilko Meyer wrote:
> 
> 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).

It is a burden to test such issues. A bunch of virtual machines helps, 
but it is necessary to start from clean user profiles each time.

>> 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.

I do not see "Other" in 
https://specifications.freedesktop.org/menu-spec/latest/apa.html but it 
caused appearance of the new section (even with localized name) in KDE, 
so it works fine.

> 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.

In kubuntu kubuntu-desktop meta-package recommends desktop-file-utils. 
Anyway with your changes the page is more helpfil than it was before.

In a minimal container xdg-open fallback functions are able to find 
.desktop file without updating of MIME types cache. Sometimes I just add

     x-scheme-handler/org-protocol=org-protocol.desktop

to
     [Default Applications]
or
     [Added Associations]
section in ~/.config/mimeapps.list to make firefox aware of it. 
Unfortunately shipped emacsclient.desktop is not suitable to just 
recommend to adjust the mimeapps.list file.

>> 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.

It seems that your approach is more productive. I tried to get more 
experience (e.g. I know that an attempt to select the emacsclient 
executable file in firefox as a custom handler leads to a silent failure 
when the browser is installed as a snap package that is new default in 
Ubuntu) so I believed that I am not ready yet to update the recipes.