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

["Robert Goldman" <rpgoldman@sift.net>]

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

On 7 Feb 2022, at 10:59, Max Nikulin wrote:

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

There are a couple of minor issues in the patch you sent (including a 
couple of grammatical errors), so attached is a revision.

I'm afraid there are now multiple patch files.

Please note that I have requested clarification at several places in the 
comment block.

Best,
R



[-- Attachment #2: 0001-Fix-FAQ-entry-about-mailto-links.patch --]
[-- Type: text/plain, Size: 1950 bytes --]

From b8158af7a839a751e6976cd95d18a5d5f199024a Mon Sep 17 00:00:00 2001
From: "Robert P. Goldman" <rpgoldman@sift.net>
Date: Thu, 6 Jan 2022 12:27:59 -0600
Subject: [PATCH 1/4] Fix FAQ entry about mailto links.

The old entry referred to the variable =org-link-mailto-program= which
was removed from org-mode almost eight years ago!  See org-mode commit
b9f2e17f07faf01109fc6f7f1eb5a34e0f97eafb
---
 org-faq.org | 18 +++++++++++++++---
 1 file changed, 15 insertions(+), 3 deletions(-)

diff --git a/org-faq.org b/org-faq.org
index 4b34560c..cac8063e 100644
--- a/org-faq.org
+++ b/org-faq.org
@@ -1927,13 +1927,13 @@ 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=:
+changing the entry for =mailto:= links in =org-link-parameters=:
 
-=M-x customize-variable org-link-mailto-program=
+=M-x customize-variable org-link-parameters=
 
 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=.
+=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=:
 
@@ -1941,6 +1941,18 @@ message buffer, you could add the following to your =.emacs=:
 (setq mail-user-agent 'gnus-user-agent)
 #+end_src
 
+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:
+
+#+begin_src elisp
+("mailto" :follow
+      (lambda
+        (path)
+        (shell-command
+         (format "open -a MailMate 'mailto:%s'" path))))
+#+end_src
+
 ** Can I use CamelCase links?
    :PROPERTIES:
    :CUSTOM_ID: CamelCase-links
-- 
2.31.1


[-- Attachment #3: 0002-Revert-Fix-FAQ-entry-about-mailto-links.patch --]
[-- Type: text/plain, Size: 1837 bytes --]

From e7f0f2c51950b3c0f181191c5210ea26cafc03f4 Mon Sep 17 00:00:00 2001
From: "Robert P. Goldman" <rpgoldman@sift.net>
Date: Thu, 10 Feb 2022 11:20:36 -0600
Subject: [PATCH 2/4] Revert "Fix FAQ entry about mailto links."

This reverts commit b8158af7a839a751e6976cd95d18a5d5f199024a.
---
 org-faq.org | 18 +++---------------
 1 file changed, 3 insertions(+), 15 deletions(-)

diff --git a/org-faq.org b/org-faq.org
index cac8063e..4b34560c 100644
--- a/org-faq.org
+++ b/org-faq.org
@@ -1927,13 +1927,13 @@ For example:
 #+index: Link!Mailto
 
 You can customize the function org-mode uses to open mailto links by
-changing the entry for =mailto:= links in =org-link-parameters=:
+setting the variable =org-link-mailto-program=:
 
-=M-x customize-variable org-link-parameters=
+=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=.
+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=:
 
@@ -1941,18 +1941,6 @@ message buffer, you could add the following to your =.emacs=:
 (setq mail-user-agent 'gnus-user-agent)
 #+end_src
 
-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:
-
-#+begin_src elisp
-("mailto" :follow
-      (lambda
-        (path)
-        (shell-command
-         (format "open -a MailMate 'mailto:%s'" path))))
-#+end_src
-
 ** Can I use CamelCase links?
    :PROPERTIES:
    :CUSTOM_ID: CamelCase-links
-- 
2.31.1


[-- Attachment #4: 0003-From-Max-Nikulin.patch --]
[-- Type: text/plain, Size: 5314 bytes --]

From 2fcf6bd07aa3e09cd11328e9e57cf3915c08a667 Mon Sep 17 00:00:00 2001
From: "Robert P. Goldman" <rpgoldman@sift.net>
Date: Thu, 10 Feb 2022 11:21:11 -0600
Subject: [PATCH 3/4] From Max Nikulin.

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


[-- Attachment #5: 0004-Further-edits-to-Max-Nikulin-s-patch.patch --]
[-- Type: text/plain, Size: 6362 bytes --]

From 9d415c3d55c3f0817598b7d746d96ae9f602623c Mon Sep 17 00:00:00 2001
From: "Robert P. Goldman" <rpgoldman@sift.net>
Date: Thu, 10 Feb 2022 11:39:53 -0600
Subject: [PATCH 4/4] Further edits to Max Nikulin's patch.

---
 org-faq.org | 84 +++++++++++++++++++++++++++++++++++------------------
 1 file changed, 55 insertions(+), 29 deletions(-)

diff --git a/org-faq.org b/org-faq.org
index b6bde3ca..1819326c 100644
--- a/org-faq.org
+++ b/org-faq.org
@@ -1926,58 +1926,84 @@ For example:
 
 #+index: Link!Mailto
 
-Org calls ~browse-url~ function for =mailto:= links, so it should obey
+Org calls the ~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
+external application instead then 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.
+and =mailto:= links will be opened according to the value of
+~browse-url~browser-function~.
 
-If you intention is to compose messages in Emacs then consult
+If you wish 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
+packages, so the next step may be to configure that variable to, e.g.,
+ =gnus-user-agent= using
+[[elisp:(customize-variable 'mail-user-agent)][=M-x customize-variable RET mail-user-agent RET=]] .
+
+If you prefer an external application that is /not/ the one configured
+in your desktop environment,
+then you should write a custom URL handler function.  Be
+careful, try to avoid using the shell (e.g. ~shell-command~ function) since it
+is easy to mess up the escaping of the URL argument and allow
+execution of arbitrary code: some parts of links may be treated as
+shell specials.  Choosing a proper function to invoke an external
 application is a non-trivial task even for seasoned Emacs developers.
-Consult source code of ~browse-url-xdg-open~,
+For examples, consult the 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.
 
 #+begin_comment
-Recurring source of pain is interaction of Emacs function with
-=xdg-open=, =kde-open5=, =gio open= utilities on Linux.  While
+A recurring source of pain for Emacs users is the interaction
+of Emacs functions with the
+=xdg-open=, =kde-open5=, and =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
+evolving to similar code in 2011.  Notice that the application has no
+chance to notify Emacs if it fails.
+
+**side comment:** the above paragraph is hard to understand. Would it be
+possible to add pointers to the discussion of these issues? Also what
+is meant by "~browse-url-xdg-open~ was evolving to similar code in
+2011."  Finally, it's not /generally/ true that subprocess
+applications can't inform Emacs of failures.  I believe that what is
+meant here is something more like "Notice that applications invoked
+through =browse-url-<foo>= have no way to notify Emacs if they fail."
+This makes sense, because browsers don't exit with a bad exit status
+if they fail to open a URL as expected. -- rpg
+
+**End of side comment**
+
+Example of this confusion:
+[[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:
+which reached the strange conclusion that it is a bug in Gnome utility:
 [[https://lists.gnu.org/archive/html/emacs-devel/2009-07/msg00279.html]]
 
+**Side comment:** The above paragraph is also difficult to parse.
+Confusion about what?  Lack of error report?  What does it mean "has
+not resulted in changing of code"? I have cut that.  Also, which Gnome
+utility do you mean here? Or did you just mean "a bug in the Gnome
+desktop"?  **End**
+
 ~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
+applications (shell is required by mailcap RFC-1524).  This approach
+can lead to user confusion such as:
+A prompt to kill
+such applications' process may appear to users to be a prompt to quit
+Emacs;
+some applications 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.
+**Please review the above edits.**
+
+Keep these considerations in mind if you decide to add more examples.
 #+end_comment
 
 When you are ready with a function launching your preferred handler
-- 
2.31.1