Add browse-url-default-handlers.feature/browse-url-handlers

* lisp/net/browse-url.el (browse-url-default-handlers): New defvar.
(browse-url--mailto, browse-url--man): New functions.
(browse-url-handlers): Improve docstring.
(browse-url): Use browse-url-default-handlers.  Adapt docstring.

1 files changed, 44 insertions, 24 deletions

diff --git a/lisp/net/browse-url.el b/lisp/net/browse-url.el
index 08b9b139202..1275c15578f 100644
--- a/lisp/net/browse-url.el
+++ b/lisp/net/browse-url.el
@@ -114,10 +114,10 @@
 ;; To always save modified buffers before displaying the file in a browser:
 ;;	(setq browse-url-save-file t)
 
-;; To invoke different browsers for different URLs:
-;;      (setq browse-url-browser-function '(("^mailto:" . browse-url-mail)
-;;      				    ("." . browse-url-firefox)))
-;; This usage is deprecated.  Use `browse-url-handlers' instead.
+;; To invoke different browsers/tools for different URLs, customize
+;; `browse-url-handlers'.  In earlier versions of Emacs, the same
+;; could be done by setting `browse-url-browser-function' to an alist
+;; but this usage is deprecated now.
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;; Code:
@@ -593,20 +593,37 @@ down (this *won't* always work)."
   "Wrapper command prepended to the Elinks command-line."
   :type '(repeat (string :tag "Wrapper")))
 
-;; ;;;###autoload ;; FIXME: This autoload breaks the build...
-(defcustom browse-url-handlers
-  `(("\\`mailto:" . ,browse-url-mailto-function)
-    ("\\`man:" . ,browse-url-man-function)
+(defun browse-url--mailto (url &rest args)
+  "Calls `browse-url-mailto-function' with URL and ARGS."
+  (funcall browse-url-mailto-function url args))
+
+(defun browse-url--man (url &rest args)
+  "Calls `browse-url-man-function' with URL and ARGS."
+  (funcall browse-url-man-function url args))
+
+;;;###autoload
+(defvar browse-url-default-handlers
+  '(("\\`mailto:" . browse-url--mailto)
+    ("\\`man:" . browse-url--man)
     ("\\`file://" . browse-url-emacs))
+  "Like `browse-url-handlers' but populated by Emacs and packages.
+
+Emacs and external packages capable of browsing certain URLs
+should place their entries in this alist rather than
+`browse-url-handlers' which is reserved for the user.")
+
+(defcustom browse-url-handlers nil
   "An alist with elements of the form (REGEXP HANDLER).
-Each REGEXP is matched against each URL to be opened in turn and
+Each REGEXP is matched against the URL to be opened in turn and
 the first match's HANDLER is invoked with the URL.
 
-A HANDLER must either be a function with the same arguments as
-`browse-url' or a variable whos value is such a function.
+A HANDLER must be a function with the same arguments as
+`browse-url'.
 
-If no REGEXP matches, the bug reference URL is opened using the
-value of `browse-url-browser-function'."
+If no REGEXP matches, the same procedure is performed with the
+value of `browse-url-default-handlers'.  If there is also no
+match, the URL is opened using the value of
+`browse-url-browser-function'."
   :type '(alist :key-type (regexp :tag "Regexp")
                 :value-type (function :tag "Handler"))
   :version "28.1")
@@ -784,16 +801,18 @@ narrowed."
   "Ask a WWW browser to load URL.
 Prompt for a URL, defaulting to the URL at or before point.
 Invokes a suitable browser function which does the actual job.
-The variable `browse-url-browser-function' says which browser function to
-use.  If the URL is a mailto: URL, consult `browse-url-mailto-function'
-first, if that exists.
-
-The additional ARGS are passed to the browser function.  See the doc
-strings of the actual functions, starting with `browse-url-browser-function',
-for information about the significance of ARGS (most of the functions
-ignore it).
-If ARGS are omitted, the default is to pass `browse-url-new-window-flag'
-as ARGS."
+
+The variables `browse-url-browser-function',
+`browse-url-handlers', and `browse-url-default-handlers'
+determine which browser function to use.
+
+The additional ARGS are passed to the browser function.  See the
+doc strings of the actual functions, starting with
+`browse-url-browser-function', for information about the
+significance of ARGS (most of the functions ignore it).
+
+If ARGS are omitted, the default is to pass
+`browse-url-new-window-flag' as ARGS."
   (interactive (browse-url-interactive-arg "URL: "))
   (unless (called-interactively-p 'interactive)
     (setq args (or args (list browse-url-new-window-flag))))
@@ -804,7 +823,8 @@ as ARGS."
   (let ((process-environment (copy-sequence process-environment))
 	(function
          (catch 'custom-url-handler
-           (dolist (regex-handler browse-url-handlers)
+           (dolist (regex-handler (append browse-url-handlers
+                                          browse-url-default-handlers))
              (when (string-match-p (car regex-handler) url)
                (throw 'custom-url-handler (cdr regex-handler))))
            ;; No special handler found.