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