From: Max Nikulin <manikulin@gmail.com>
To: emacs-orgmode@gnu.org
Cc: Robert Goldman <rpgoldman@sift.net>
Subject: [PATCH v3] Fix FAQ entry about mailto links.
Date: Mon, 14 Feb 2022 20:22:14 +0700 [thread overview]
Message-ID: <9437ade2-af18-f97e-8790-a2df27c9017c@gmail.com> (raw)
In-Reply-To: <11DC93C5-2600-4B6B-B7E0-B200AB274C35@sift.net>
[-- Attachment #1: Type: text/plain, Size: 4944 bytes --]
On 11/02/2022 00:42, Robert Goldman wrote:
>
> There are a couple of minor issues in the patch you sent (including a
> couple of grammatical errors), so attached is a revision.
Great. Thank you, Robert, it exact reason why I asked for a review.
I am sending the updated patch and a diff to your edits to highlight my
latest changes.
> 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.
Would you like to have you original version in git history? For me it is
not a problem to make my patch updating yours one without reverting the
original commit (create another branch, cherry-pick commits, resolve
conflict to the latest state). Otherwise you can avoid unnecessary
commits in your local repository by either applying my patch to a new
branch or using "git rebase -i master" to drop unnecessary commits.
> +If you prefer an external application that is /not/ the one configured
> +in your desktop environment,
What is bothering me a bit is the entry title "Org-mode is not opening
mailto links in my *default* mail client". The updated variant mostly
discusses changing of defaults.
> +**side comment:** the above paragraph is hard to understand. Would it be
> +possible to add pointers to the discussion of these issues?
I do not follow Emacs development. The source is git commit history and
commit messages rarely have links to discussion or references to bug
tracker.
> 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.
The reality is that failures of xdg-open are confusingly quiet. Often
nil is specified as the buffer for standard error (application may spam
with warnings and failed assert). For `start-process' or `make-process'
it is necessary to create a handler that displays message on process
failure. `call-process' with 0 as DESTINATION signals error only if it
can not find the executable otherwise only desktop environment may
notify user about an error.
> 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
It is another sort of errors and browser may show an error page. Notice
that executable may just send a command to an already running process
and to exit almost instantly.
> +which reached the strange conclusion that it is a bug in Gnome utility:
I would not say "reached". The statement appeared in the middle of
discussion and the problem was not fixed that time.
> +**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**
Confusion whether nohup wrapper is necessary. It was removed a bit
earlier by a participant of the discussion of the bug 9779 and I believe
that the change was correct since dropping of nohup was accompanied by
other changes. I do not remember what was the name of the gnome utility
that time, maybe gnome-open, currently it is "gio open" but for most of
people it is anyway hidden behind xdg-open and namely xdg-open usually
becomes the target to blame.
> On 7 Feb 2022, at 10:59, Max Nikulin wrote:
>> +#+begin_comment
>> +Recurring source of pain is interaction of Emacs function with
Notice that comment is dropped during export, it is visible only to
contributors who will decide to update the entry. I am unsure where
such note should be placed: separate worg page, emacswiki site, etc.
Even Org has several files with quite similar problems with launching of
viewers.
>> +[[elisp:(customize-variable 'org-link-parameters)][=M-x customize-variable RET org-link-parameters RET=]], e.g. for
Actually I am unsure if customization of `org-link-parameters' should be
recommended. The interface contains a lot of entries actually added by
org packages. Maybe it is better to suggest
(with-eval-after-load 'ol
(org-link-set-parameters
;; ...
>> +#+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))))
^^^^^^^
Notice this addition, I can not test if it really works.
>> #+end_src
[-- Attachment #2: 0001-FAQ-Update-suggestion-for-mailto-link-handlers.patch --]
[-- Type: text/x-patch, Size: 6771 bytes --]
From 8eeb353a45521ab34cced37971e4455f870671c9 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.
This change is prepared in cooperation with Robert Goldman <rpgoldman@sift.net>,
see https://list.orgmode.org/FEAD92A6-87DE-4CFF-8459-E3D012DD3F52@sift.net
for the initial suggestion.
---
org-faq.org | 104 ++++++++++++++++++++++++++++++++++++++++++++++------
1 file changed, 93 insertions(+), 11 deletions(-)
diff --git a/org-faq.org b/org-faq.org
index 4b34560c..323fba6b 100644
--- a/org-faq.org
+++ b/org-faq.org
@@ -1926,21 +1926,103 @@ 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 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 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 according to the value of
+~browse-url~browser-function~.
+
+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 and the active one is determined by the ~mail-user-agent~ variable,
+so the next step may be to configure it 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.
+When possible use an option like double dash =--= before URLs that forces
+interpreting following as arguments even when a string resembles some option
+due to a leading dash.
+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.
-=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
+A recurring source of pain for 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, the introduced later
+~browse-url-xdg-open~ function was evolving to similar code in 2011.
+See commit history for earlier steps. Notice that with the ~call-process~
+approach the application has no chance to notify Emacs if it fails.
+
+Example of confusion with techniques to launch applications is comment
+[[https://debbugs.gnu.org/cgi/bugreport.cgi?bug=9779#29]]
+that falsely points out to missed =nohup= despite of usage the ~call-process~ function.
+Its choice is not intuitive since normally ~call-process~
+waits till process completion. However with 0 (not ~nil~!) argument
+it creates a completely detached process.
+It is asynchronous ~start-process~
+and ~make~process~ functions that create a pty by default and so kill
+children by =SIGHUP= signal when the main process exits after fork.
+There was
+a lengthy thread "& and M-& to run programs asynchronously" in 2009
+with a comment containing a strange conclusion that immediate exit is a bug
+in the Gnome CLI utility launching MIME handler:
+[[https://lists.gnu.org/archive/html/emacs-devel/2009-07/msg00279.html]].
+
+~org-open-file~ and ~mailcap-view-mime~ functions create asynchronous processes to launch
+applications (shell is required by mailcap RFC-1524 so the code does not follow the recommendation given above),
+but they use pipe processes instead of default pty ones.
+This approach has downsides as well. In some cases application can not run longer
+than Emacs (a prompt to confirm its termination may appear on attempt to quit from 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.
+
+Keep these considerations 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
[-- Attachment #3: faq-mailto-changes-since-2022-02-11-goldman.diff --]
[-- Type: text/x-patch, Size: 6285 bytes --]
commit e151f6d800e216ba2586b309f777efed81197572
Author: Max Nikulin <manikulin@gmail.com>
Date: Mon Feb 14 19:21:54 2022 +0700
[DRAFT] Diff to Robert P. Goldman's revision
This is not a real patch. The intention is to show
changes made in response to the review.
diff --git a/org-faq.org b/org-faq.org
index 1819326c..323fba6b 100644
--- a/org-faq.org
+++ b/org-faq.org
@@ -1932,7 +1932,7 @@ your Emacs configuration. If something goes wrong then
By default mail is composed in an Emacs buffer. If you prefer some
external application instead then set ~browse-url-mailto-function~ to
-=nil=, e.g. using
+~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 according to the value of
~browse-url~browser-function~.
@@ -1940,9 +1940,9 @@ and =mailto:= links will be opened according to the value of
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 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=]] .
+packages and the active one is determined by the ~mail-user-agent~ variable,
+so the next step may be to configure it 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,
@@ -1952,57 +1952,48 @@ 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.
+When possible use an option like double dash =--= before URLs that forces
+interpreting following as arguments even when a string resembles some option
+due to a leading dash.
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
-A recurring source of pain for Emacs users is the interaction
+A recurring source of pain for 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 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]]
+~browse-url-generic~ was settled in 2004, the introduced later
+~browse-url-xdg-open~ function was evolving to similar code in 2011.
+See commit history for earlier steps. Notice that with the ~call-process~
+approach the application has no chance to notify Emacs if it fails.
+
+Example of confusion with techniques to launch applications is comment
+[[https://debbugs.gnu.org/cgi/bugreport.cgi?bug=9779#29]]
+that falsely points out to missed =nohup= despite of usage the ~call-process~ function.
+Its choice is not intuitive since normally ~call-process~
+waits till process completion. However with 0 (not ~nil~!) argument
+it creates a completely detached process.
+It is asynchronous ~start-process~
+and ~make~process~ functions that create a pty by default and so kill
+children by =SIGHUP= signal when the main process exits after fork.
There was
a lengthy thread "& and M-& to run programs asynchronously" in 2009
-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
-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
+with a comment containing a strange conclusion that immediate exit is a bug
+in the Gnome CLI utility launching MIME handler:
+[[https://lists.gnu.org/archive/html/emacs-devel/2009-07/msg00279.html]].
+
+~org-open-file~ and ~mailcap-view-mime~ functions create asynchronous processes to launch
+applications (shell is required by mailcap RFC-1524 so the code does not follow the recommendation given above),
+but they use pipe processes instead of default pty ones.
+This approach has downsides as well. In some cases application can not run longer
+than Emacs (a prompt to confirm its termination may appear on attempt to quit from 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.
-**Please review the above edits.**
-
Keep these considerations in mind if you decide to add more examples.
#+end_comment
next prev parent reply other threads:[~2022-02-14 13:46 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
2022-02-10 17:42 ` Robert Goldman
2022-02-14 13:22 ` Max Nikulin [this message]
2022-02-16 1:29 ` [PATCH v3] " 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:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
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=9437ade2-af18-f97e-8790-a2df27c9017c@gmail.com \
--to=manikulin@gmail.com \
--cc=emacs-orgmode@gnu.org \
--cc=rpgoldman@sift.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* 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
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
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).