From 0191077d6a96d9ef8e43989fd5dc8a95e61806d5 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 26 Dec 2015 20:47:42 +0200 Subject: [PATCH] Fix documentation of browse-url browser-related functions * lisp/net/browse-url.el (browse-url) (browse-url-default-browser, browse-url-default-windows-browser) (browse-url-default-macosx-browser, browse-url-chromium) (browse-url-kde, browse-url-text-xterm): Clarify the usage of ARGS and NEW-WINDOW arguments in these functions. (Bug#19421) --- lisp/net/browse-url.el | 30 +++++++++++++++++++++--------- 1 file changed, 21 insertions(+), 9 deletions(-) diff --git a/lisp/net/browse-url.el b/lisp/net/browse-url.el index feb0788db92..d232c8add13 100644 --- a/lisp/net/browse-url.el +++ b/lisp/net/browse-url.el @@ -762,12 +762,17 @@ narrowed." (defun browse-url (url &rest args) "Ask a WWW browser to load URL. Prompt for a URL, defaulting to the URL at or before point. -The variable `browse-url-browser-function' says which browser to use. -If the URL is a mailto: URL, consult `browse-url-mailto-function' +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. -Passes any ARGS to the browser function. -The default is to pass `browse-url-new-window-flag'." +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)))) @@ -836,6 +841,8 @@ says which browser to use." (declare-function w32-shell-execute "w32fns.c") ;; Defined in C. (defun browse-url-default-windows-browser (url &optional _new-window) + "Invoke the MS-Windows system's default Web browser. +The optional NEW-WINDOW argument is not used." (interactive (browse-url-interactive-arg "URL: ")) (cond ((eq system-type 'ms-dos) (if dos-windows-version @@ -846,6 +853,8 @@ says which browser to use." (t (w32-shell-execute "open" url)))) (defun browse-url-default-macosx-browser (url &optional _new-window) + "Invoke the MacOS X system's default Web browser. +The optional NEW-WINDOW argument is not used" (interactive (browse-url-interactive-arg "URL: ")) (start-process (concat "open " url) nil "open" url)) @@ -880,8 +889,8 @@ non-nil, load the document in a new window, if possible, otherwise use a random existing one. A non-nil interactive prefix argument reverses the effect of `browse-url-new-window-flag'. -When called non-interactively, optional second argument NEW-WINDOW is -used instead of `browse-url-new-window-flag'." +When called non-interactively, optional second argument ARGS is used +instead of `browse-url-new-window-flag'." (apply (cond ((memq system-type '(windows-nt ms-dos cygwin)) @@ -1103,7 +1112,8 @@ instead of `browse-url-new-window-flag'." "Ask the Chromium WWW browser to load URL. Default to the URL around or before point. The strings in variable `browse-url-chromium-arguments' are also passed to -Chromium." +Chromium. +The optional argument NEW-WINDOW is not used." (interactive (browse-url-interactive-arg "URL: ")) (setq url (browse-url-encode-url url)) (let* ((process-environment (browse-url-process-environment))) @@ -1412,7 +1422,8 @@ The `browse-url-gnudoit-program' program is used with options given by URL defaults to the URL around or before point. This runs the text browser specified by `browse-url-text-browser'. in an Xterm window using the Xterm program named by `browse-url-xterm-program' -with possible additional arguments `browse-url-xterm-args'." +with possible additional arguments `browse-url-xterm-args'. +The optional argument NEW-WINDOW is not used." (interactive (browse-url-interactive-arg "Text browser URL: ")) (apply #'start-process `(,(concat browse-url-text-browser url) nil ,browse-url-xterm-program @@ -1560,7 +1571,8 @@ don't offer a form of remote control." ;;;###autoload (defun browse-url-kde (url &optional _new-window) "Ask the KDE WWW browser to load URL. -Default to the URL around or before point." +Default to the URL around or before point. +The optional argument NEW-WINDOW is not used." (interactive (browse-url-interactive-arg "KDE URL: ")) (message "Sending URL to KDE...") (apply #'start-process (concat "KDE " url) nil browse-url-kde-program -- 2.39.2