Re: [PATCH] Fix FAQ entry about mailto links.

[Max Nikulin <manikulin@gmail.com>]

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

Robert,

Thank you for pointing out that `org-link-mailto-program' should not be 
recommended in FAQ any more.

I prepared an alternative patch that recommends to customize Emacs 
variables at first. I hope, an example is safer now, however I can not 
test it on MacOS. Could you, please, review the patch, since I may miss 
something important from your point of view?

On 07/01/2022 18:03, Max Nikulin wrote:
> On 07/01/2022 01:34, Robert Goldman wrote:
>>
>> +You can also change the function used to a different one.  For
>> +example, the following function (on MacOS) opens =mailto:= links in
>> +the =MailMate= program:

I am unsure if MailMate is acceptable since it is a proprietary 
application. Org is a part of *GNU* Emacs, so it may be better to 
mention some free mail user agent.

>> +#+begin_src elisp
>> +("mailto" :follow
>      ^
> It seems, `org-link-set-parameters' is missed.

I am sorry, I missed that you suggested to customize the 
`org-link-parameters' variable, so function call is not necessary here.

[-- Attachment #2: 0001-FAQ-Update-suggestion-for-mailto-link-handlers.patch --]
[-- Type: text/x-patch, Size: 5869 bytes --]

From 2ace01016588884f61361b6f37bf3273f8520f2c Mon Sep 17 00:00:00 2001
From: Max Nikulin <manikulin@gmail.com>
Date: Mon, 7 Feb 2022 23:40:37 +0700
Subject: [PATCH] FAQ: Update suggestion for mailto: link handlers

org-faq.org (mailto-links): Mention `org-link-mailto-program' as removed
variable, recommend customization of `browse-url-mailto-function' or
`org-link-parameters' instead.

Robert Goldman <rpgoldman@sift.net> in
https://list.orgmode.org/FEAD92A6-87DE-4CFF-8459-E3D012DD3F52@sift.net
proposed a patch removing mention of `org-link-mailto-program' variable
that is not used in the code for some time.  The patch has an example of
usage `org-link-parameters' to assign custom external handler for
mailto: links.

This change recommends to configure Emacs facilities used by Org as
well.  It has a safer example for `org-link-parameters' customization.
---
 org-faq.org | 87 ++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 76 insertions(+), 11 deletions(-)

diff --git a/org-faq.org b/org-faq.org
index 4b34560c..b6bde3ca 100644
--- a/org-faq.org
+++ b/org-faq.org
@@ -1926,21 +1926,86 @@ For example:
 
 #+index: Link!Mailto
 
-You can customize the function org-mode uses to open mailto links by
-setting the variable =org-link-mailto-program=:
+Org calls ~browse-url~ function for =mailto:= links, so it should obey
+your Emacs configuration.  If something goes wrong then
+[[info:emacs#Browse-URL][info "(emacs) Browse-URL"]] may be a good starting point.
+
+By default mail is composed in an Emacs buffer.  If you prefer some
+external application instead than set ~browse-url-mailto-function~ to
+nil, e.g. using
+[[elisp:(customize-variable 'browse-url-mailto-function)][=M-x customize-variable RET browse-url-mailto-function RET=]]
+and =mailto:= links will be opened accordingly to
+~browse-url~browser-function~ value.
+
+If you intention is to compose messages in Emacs then consult
+[[info:emacs#Mail Methods][info "(emacs) Mail Methods"]].  Check that ~browse-url-mailto-function~
+has its default value ~browse-url-mail~.  Emacs has several mail
+packages, so next step may be
+[[elisp:(customize-variable 'mail-user-agent)][=M-x customize-variable RET mail-user-agent RET=]] to set the variable
+to e.g. =gnus-user-agent=.
+
+If you prefer an external application other than configured in desktop
+environment then you should write a custom URL handler function.  Be
+careful, try to avoid shell (e.g. ~shell-command~ function) since it
+is easy to mess up with escaping of the URL argument and thus to allow
+execution of arbitrary code.  Some parts of links may be treated as
+shell specials.  Choosing of a proper function to invoke external
+application is a non-trivial task even for seasoned Emacs developers.
+Consult source code of ~browse-url-xdg-open~,
+~browse-url-default-macosx-browser~, or
+~browse-url-default-windows-browser~ for GNU/Linux,
+Mac\nbsp{}OS\nbsp{}X, or MS\nbsp{}Windows platforms accordingly.
 
-=M-x customize-variable org-link-mailto-program=
-
-The default function called is =browse-url=, which opens a mail
-composition buffer within Emacs. The type of buffer opened by
-browse-url depends on the setting of the variable =mail-user-agent=.
-Thus, if you want to ensure that mailto links use Gnus to open a
-message buffer, you could add the following to your =.emacs=:
+#+begin_comment
+Recurring source of pain is interaction of Emacs function with
+=xdg-open=, =kde-open5=, =gio open= utilities on Linux.  While
+~call-process~ with 0 as ~DESTINATION~ argument for
+~browse-url-generic~ was settled in 2004, ~browse-url-xdg-open~ was
+evolving to similar code in 2011.  Notice that application has no
+chance to notify Emacs about failure.
+
+Example of confusion that fortunately was not resulted in changing of
+code: [[https://debbugs.gnu.org/cgi/bugreport.cgi?bug=9779#29]] There was
+a lengthy thread "& and M-& to run programs asynchronously" in 2009
+with strange conclusion that it is a bug in Gnome utility:
+[[https://lists.gnu.org/archive/html/emacs-devel/2009-07/msg00279.html]]
+
+~org-open-file~ and ~mailcap-view-mime~ use another approach to launch
+application (shell is required by mailcap RFC-1524).  A prompt to kill
+process may appear quitting from Emacs, some application might cause
+high CPU consumption by Emacs.  See
+https://debbugs.gnu.org/cgi/bugreport.cgi?bug=44824 and
+https://debbugs.gnu.org/cgi/bugreport.cgi?bug=12972 for details.
+
+Have this in mind if you decide to add more examples.
+#+end_comment
 
-#+begin_src elisp
-(setq mail-user-agent 'gnus-user-agent)
+When you are ready with a function launching your preferred handler
+for =mailto:= links, you should add it to ~browse-url-handlers~
+associations list for Emacs-28.1 and newer or to
+~browse-url-browser-function~ for earlier versions by customizing the
+suitable variable.
+
+If you are going to change handler just in Org mode in a way that does
+not affect rest of Emacs than you can adjust it through
+[[elisp:(customize-variable 'org-link-parameters)][=M-x customize-variable RET org-link-parameters RET=]], e.g. for
+Mac\nbsp{}OS\nbsp{}X link property may be following (on Linux to avoid
+silent failures add ~(process-connection-type nil)~ to ~let~ variables
+or use ~call-process~ with =0= as the =DESTINATION= argument):
+
+#+begin_src elisp :results none
+("mailto"
+ :follow (lambda (path)
+	   (let ((url (concat "mailto:" path)))
+	     ;; platform-specific choice of function
+	     (start-process (concat "open " url) nil
+			    "open" "-a" "Thunderbird" "--args" url))))
 #+end_src
 
+In earlier versions Org had ~org-link-mailto-program~ variable, but it
+was removed, so its customization does not work any more.  Update your
+init file if you noticed this variable.
+
 ** Can I use CamelCase links?
    :PROPERTIES:
    :CUSTOM_ID: CamelCase-links
-- 
2.25.1