feature/browse-url-handlers c5e2d0c: Deprecate alist value of browse-url-browser-function.

[Tassilo Horn]

branch: feature/browse-url-handlers
commit c5e2d0c7d6334bd0eeb6274266a5315ae5f0ea8b
Author: Tassilo Horn <address@hidden>
Commit: Tassilo Horn <address@hidden>

    Deprecate alist value of browse-url-browser-function.
    
    * lisp/net/browse-url.el (browse-url--browser-defcustom-type): Add
    :doc that the alist usage is deprecated.
    (browse-url-browser-function): Remove documentation referring to the
    alist usage and mention browse-url-handlers.
    (browse-url): Issue a warning pointing to browse-url-handlers when
    browse-url-browser-function is an alist.
---
 lisp/net/browse-url.el | 37 +++++++++++++++++++------------------
 1 file changed, 19 insertions(+), 18 deletions(-)

diff --git a/lisp/net/browse-url.el b/lisp/net/browse-url.el
index 934fd66..0a8816a 100644
--- a/lisp/net/browse-url.el
+++ b/lisp/net/browse-url.el
@@ -117,6 +117,7 @@
 ;; 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.
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;; Code:
@@ -157,7 +158,8 @@
                   :value browse-url-default-browser)
     (function :tag "Your own function")
     (alist :tag "Regexp/function association list"
-          :key-type regexp :value-type function)))
+          :key-type regexp :value-type function
+           :doc "Deprecated.  Use `browse-url-handlers' instead.")))
 
 ;;;###autoload
 (defcustom browse-url-browser-function 'browse-url-default-browser
@@ -165,13 +167,8 @@
 This is used by the `browse-url-at-point', `browse-url-at-mouse', and
 `browse-url-of-file' commands.
 
-If the value is not a function it should be a list of pairs
-\(REGEXP . FUNCTION).  In this case the function called will be the one
-associated with the first REGEXP which matches the current URL.  The
-function is passed the URL and any other args of `browse-url'.  The last
-regexp should probably be \".\" to specify a default browser.
-
-Also see `browse-url-secondary-browser-function'."
+Also see `browse-url-secondary-browser-function' and
+`browse-url-handlers'."
   :type browse-url--browser-defcustom-type
   :version "24.1")
 
@@ -595,7 +592,7 @@ down (this *won't* always work)."
   "Wrapper command prepended to the Elinks command-line."
   :type '(repeat (string :tag "Wrapper")))
 
-;;;###autoload
+;; ;;;###autoload ;; FIXME: This autoload breaks the build...
 (defcustom browse-url-handlers
   `(("\\`mailto:"; . ,browse-url-mailto-function)
     ("\\`man:" . ,browse-url-man-function)
@@ -821,15 +818,19 @@ as ARGS."
         (setenv "DISPLAY" (frame-parameter nil 'display)))
     (if (and (consp function)
             (not (functionp function)))
-       ;; The `function' can be an alist; look down it for first match
-       ;; and apply the function (which might be a lambda).
-       (catch 'done
-         (dolist (bf function)
-           (when (string-match (car bf) url)
-             (apply (cdr bf) url args)
-             (throw 'done t)))
-         (error "No browse-url-browser-function matching URL %s"
-                url))
+       ;; The `function' can be an alist; look down it for first
+       ;; match and apply the function (which might be a lambda).
+       ;; However, this usage is deprecated as of Emacs 28.1.
+        (progn
+          (warn "Having `browse-url-browser-function' set to an
+alist is deprecated.  Use `browse-url-handlers' instead.")
+          (catch 'done
+           (dolist (bf function)
+             (when (string-match (car bf) url)
+               (apply (cdr bf) url args)
+               (throw 'done t)))
+           (error "No browse-url-browser-function matching URL %s"
+                  url)))
       ;; Unbound symbols go down this leg, since void-function from
       ;; apply is clearer than wrong-type-argument from dolist.
       (apply function url args))))