bug#30981: Document how to use $BROWSER for external browser

["積丹尼 Dan Jacobson" <jidanni@jidanni.org>]

Gentleman, other programs know to just use $BROWSER when calling the
external browser. But for emacs and gnus, one must hire a consultant to
achieve the same effect.

At least one of the manuals should say how.

And in fact, if $BROWSER is good enough for other programs, it should be
the default for emacs/gnus too.

>>>>> "KY" == Katsumi Yamaoka <yamaoka@jpl.org> writes:
KY> On Tue, 27 Mar 2018 09:31:34 +0800, 積丹尼さん wrote:
>> RET runs the command shr-browse-url, which is an interactive compiled
>> Lisp function in ‘shr.el’.

KY> `shr-browse-url' runs the Lisp function `browse-url' (unless the
KY> prefix argument is given when invoking `shr-browse-url').
KY> So, in the normal way that browse-url's author supposed, you can
KY> choose a certain ready-made Lisp function as you like as follows:

KY> (setq browse-url-browser-function #'browse-url-firefox)

KY> To see the ready-made functions you can use, do:

KY> M-x customize-option RET browse-url-browser-function RET

KY> ;; You will see browse-url-firefox, browse-url-chromium, etc.

>> I want it to call $BROWSER from the environment.

>> ;;(if (string-equal (getenv "BROWSER") "chromium")
>> ;;    nil (setq browse-url-chromium-program
>> ;;	      (concat "/usr/bin/" (getenv "BROWSER")))) ;I am a dork
>> (setq browse-url-default-browser (getenv "BROWSER"))

KY> `browse-url-default-browser' is a function, not a variable, and
KY> is one of candidates for `browse-url-browser-function'.  So,
KY> this (setq ...) form has no effect.  But you are not a dork. :-)
Wrong.
KY> You can create your own Lisp function that sees "BROWSER".
KY> For example:

KY> (setq browse-url-browser-function #'my-browse-url-default-browser)

KY> (defun my-browse-url-default-browser (url &optional _dummy)
KY>   "Run a browser that the environment variable BROWSER specifies.
KY> BROWSER may be an existing shell command name, or a command name plus
KY> some arguments like: \"firefox\", or \"firefox -new-tab\""
KY>   (interactive (browse-url-interactive-arg "URL: "))
KY>   (let ((process-environment (browse-url-process-environment))
KY> 	(browser (getenv "BROWSER"))
KY> 	args name)
KY>     (setq browser (split-string browser)
KY> 	  args (cdr browser)
KY> 	  browser (car browser)
KY> 	  name (concat (file-name-nondirectory browser)
KY> 		       " " (mapconcat #'identity args " ")
KY> 		       " " url)
KY> 	  url (browse-url-encode-url url))
KY>     (apply 'start-process name nil (executable-find browser)
KY> 	   (append args (list url)))))

Waaa... it actually works! Thanks!