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.From 2ace01016588884f61361b6f37bf3273f8520f2c Mon Sep 17 00:00:00 2001
From: Max Nikulin <maniku...@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 <rpgold...@sift.net> in
https://list.orgmode.org/fead92a6-87de-4cff-8459-e3d012dd3...@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
