emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Max Nikulin <manikulin@gmail.com>
To: emacs-orgmode@gnu.org
Cc: Robert Goldman <rpgoldman@sift.net>
Subject: Re: [PATCH] Fix FAQ entry about mailto links.
Date: Mon, 7 Feb 2022 23:59:54 +0700	[thread overview]
Message-ID: <a6c55335-c9dd-b3c7-8253-2a83e46e9b37@gmail.com> (raw)
In-Reply-To: <sr96lp$jf8$1@ciao.gmane.io>

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


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
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=:
+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:
+~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.
-#+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
+ :follow (lambda (path)
+	   (let ((url (concat "mailto:" path)))
+	     ;; platform-specific choice of function
+	     (start-process (concat "open " url) nil
+			    "open" "-a" "Thunderbird" "--args" url))))
+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?
    :CUSTOM_ID: CamelCase-links

  reply	other threads:[~2022-02-07 17:32 UTC|newest]

Thread overview: 9+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-01-06 18:34 [PATCH] Fix FAQ entry about mailto links Robert Goldman
2022-01-07 11:03 ` Max Nikulin
2022-02-07 16:59   ` Max Nikulin [this message]
2022-02-10 17:42     ` Robert Goldman
2022-02-14 13:22       ` [PATCH v3] " Max Nikulin
2022-02-16  1:29         ` Robert Goldman
2022-02-25 12:20           ` Max Nikulin
2022-03-12 14:35             ` Max Nikulin
2022-03-12 15:50 ` [PATCH] " Max Nikulin

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

  List information: https://www.orgmode.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=a6c55335-c9dd-b3c7-8253-2a83e46e9b37@gmail.com \
    --to=manikulin@gmail.com \
    --cc=emacs-orgmode@gnu.org \
    --cc=rpgoldman@sift.net \


* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox


This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).