Subject: Re: bug#69627: 30.0.50; [PATCH] Allow 'browse-url-interactive-arg' to return the actual prefix arg

From: Jim Porter <[email-masked]>
Date: Fri, 8 Mar 2024 10:29:05 -0800

On 3/7/2024 11:43 PM, Eli Zaretskii wrote:
> Shouldn't the effect of this change be documented in some doc string?

How about this? I'm not sure if using "xor" in the docstrings is 
over-explaining things, but then I don't know if there's a better way to 
describe exactly what would happen.

From c4842dacc734b75747e66255bc12e175457c871a Mon Sep 17 00:00:00 2001
From: Jim Porter <[email-masked]>
Date: Thu, 7 Mar 2024 21:55:45 -0800
Subject: [PATCH] Let 'browse-url-interactive-arg' return more values for
 NEW-WINDOW-FLAG

Previously it always returned t or nil for NEW-WINDOW-FLAG, but now it
can return the actual prefix arg when appropriate.  This lets functions
for 'browse-url-browser-function' consult it and do more things than
just open a new window or not (for example, you could use "C--" as the
prefix arg to do something special in a custom function).

* lisp/net/browse-url.el (browse-url-interactive-arg): Use 'xor' to
adjust the value of 'current-prefix-arg'.
(browse-url): Update docstring.
---
 lisp/net/browse-url.el | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/lisp/net/browse-url.el b/lisp/net/browse-url.el
index ddc57724343..8d28a6ce7c6 100644
--- a/lisp/net/browse-url.el
+++ b/lisp/net/browse-url.el
@@ -704,8 +704,9 @@ browse-url-interactive-arg
 point.  If invoked with a mouse button, it moves point to the
 position clicked before acting.
 
-This function returns a list (URL NEW-WINDOW-FLAG)
-for use in `interactive'."
+This function returns a list (URL NEW-WINDOW-FLAG) for use in
+`interactive'.  NEW-WINDOW-FLAG is either the prefix arg xor
+`browse-url-new-window-flag'."
   (let ((event (elt (this-command-keys) 0)))
     (mouse-set-point event))
   (list (read-string prompt (or (and transient-mark-mode mark-active
@@ -715,8 +716,7 @@ browse-url-interactive-arg
 				      (buffer-substring-no-properties
 				       (region-beginning) (region-end))))
 				(browse-url-url-at-point)))
-	(not (eq (null browse-url-new-window-flag)
-		 (null current-prefix-arg)))))
+	(xor browse-url-new-window-flag current-prefix-arg)))
 
 ;; called-interactive-p needs to be called at a function's top-level, hence
 ;; this macro.  We use that rather than interactive-p because
@@ -879,8 +879,8 @@ browse-url
 `browse-url-handlers', and `browse-url-default-handlers'
 determine which browser function to use.
 
-This command prompts for a URL, defaulting to the URL at or
-before point.
+Interactively, this command prompts for a URL, defaulting to the
+URL at or before point.
 
 The additional ARGS are passed to the browser function.  See the
 doc strings of the actual functions, starting with
@@ -888,7 +888,8 @@ browse-url
 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."
+`browse-url-new-window-flag' as ARGS.  Interactively, pass the
+prefix arg xor `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))))
-- 
2.25.1