Re: bug-reference.el: Allow custom handlers for opening URLs

[Tassilo Horn <tsdh@gnu.org>]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> And when hacking that up, I've seen that this feature is already
>> implemented!
>>
>> The value of `browse-url-browser-function' may already be a (REGEXP
>> . FUNCTION) alist itself and then it works the same way as my new
>> `browse-url-handlers'.
>
> Hmm... right.  Ideally we should have 2 places to specify those
> redirections: one autoload-set by packages to change the default
> behavior, and one custom-set by the user to override that default
> behavior.

So you mean we need to have a `browse-url-handlers' defcustom and a
`browse-url-handlers-default' defvar?  Maybe you are right.  On the
other hand, we haven't something like that for similar candidates like
`auto-mode-alist', too.  There, we use the "if you don't like it, remove
it yourself" approach.

Another way would be to cross fingers and hope that package authors are
responsible enough to provide a defcustom which controls if a handler is
added to `browse-url-handlers'.  That would be much more convenient as
both adding an override and removing an entry.

> But if we use `browse-url-browser-function` as the user-override, then
> as soon as the user sets it to `browse-url-firefox` it would override
> all the defaults :-(
>
> So we still need to deprecate this old hack on
> `browse-url-browser-function`.

Right.

>> But removing the alist from `browse-url--browser-defcustom-type'
>> would break the customize interface if the user's value is indeed an
>> alist...  So is there a better way to deprecate a single choice of a
>> defcustom type?  Just writing that in the docstring?
>
> Good question, hopefully someone else knows.

Hm, the info docs say that every custom type may have a :doc string:

--8<---------------cut here---------------start------------->8---
‘:doc DOC’
     Use DOC as the documentation string for this value (or part of the
     value) that corresponds to this type.  In order for this to work,
     you must specify a value for ‘:format’, and use ‘%d’ or ‘%h’ in
     that value.

     The usual reason to specify a documentation string for a type is to
     provide more information about the meanings of alternatives inside
     a ‘:choice’ type or the parts of some other composite type.
--8<---------------cut here---------------end--------------->8---

That second paragraph sounds exactly like what we would need, so I added

  :doc "Deprecated.  Use `browse-url-handlers' instead."

to the alist choice.  However, I cannot see that in the customize
interface.  Am I doing something wrong?

And another question.  The definition below breaks the build.

--8<---------------cut here---------------start------------->8---
;;;###autoload ;; FIXME: This autoload breaks the build...
(defcustom browse-url-handlers
  `(("\\`mailto:" . ,browse-url-mailto-function)
    ("\\`man:" . ,browse-url-man-function)
    ("\\`file://" . browse-url-emacs))
  "An alist with elements of the form (REGEXP HANDLER).
Each REGEXP is matched against each 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.

If no REGEXP matches, the bug reference 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")
--8<---------------cut here---------------end--------------->8---

The error is:

--8<---------------cut here---------------start------------->8---
Loading files...
Loading emacs-lisp/macroexp...
Loading cus-face...
Loading faces...
Loading button...
Loading loaddefs.el (source)...
Symbol's value as variable is void: browse-url-mailto-function
make[2]: *** [Makefile:584: emacs.pdmp] Error 255
make[2]: Leaving directory '/home/horn/Repos/el/emacs/src'
make[1]: *** [Makefile:424: src] Error 2
make[1]: Leaving directory '/home/horn/Repos/el/emacs'
make: *** [Makefile:1119: bootstrap] Error 2
--8<---------------cut here---------------end--------------->8---

When removing the autoload cookie, it builds fine.  Why is that?
`browse-url-mailto-function' and `browse-url-man-function' are defined
way before `browse-url-handlers'.

Bye,
Tassilo