From 2fcf6bd07aa3e09cd11328e9e57cf3915c08a667 Mon Sep 17 00:00:00 2001 From: "Robert P. Goldman" 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