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

[Max Nikulin <manikulin@gmail.com>]

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?