doc-lookup: use BROWSER variable; provide fallback.

* stdlib/doc-lookup.tl (open-url): On non-Windows platforms,
search for a program specified by the BROWSER variable,
then by the URL-opening utility, and finally thorugh a
fallback list of browsers.

* txr.1: Documentation updated.

2 files changed, 40 insertions, 5 deletions

diff --git a/stdlib/doc-lookup.tl b/stdlib/doc-lookup.tl
index 1d02049e..110d37d4 100644
--- a/stdlib/doc-lookup.tl
+++ b/stdlib/doc-lookup.tl
@@ -28,11 +28,21 @@
 (caseql os-symbol
   ((:linux :macos :solaris :solaris10 :android)
    (defun open-url (url)
-     (detached-run (caseql os-symbol
+     (let ((opener (caseql os-symbol
                      ((:linux :solaris :android) "xdg-open")
                      (:solaris10 "/usr/dt/bin/sdtwebclient")
-                     (:macos "open"))
-                   (list url))))
+                     (:macos "open")))
+           (fallback '#"firefox iceweasel seamonkey mozilla \
+                        epiphany konqueror chromium chromium-browser \
+                        google-chrome"))
+       (let ((prog (or (getenv "BROWSER")
+                       (if (abs-path-p opener)
+                         opener
+                         (path-search opener))
+                       [find-true path-search fallback])))
+         (if prog
+           (detached-run prog (list url))
+           (error "~s: no URL-opening method available" 'open-url))))))
   ((:cygwin :cygnal)
    (with-dyn-lib "shell32.dll"
      (deffi shell-execute "ShellExecuteW"
diff --git a/txr.1 b/txr.1
index 75234425..db8bba50 100644
--- a/txr.1
+++ b/txr.1
@@ -82147,8 +82147,8 @@ function provides help for the library symbol
 If information about
 .meta symbol
 is available in the HTML version of this document, and is indexed, then this
-function causes that document to be opened using the system's default web
-browser, such that the browser navigates to the appropriate section of
+function causes that document to be opened using a web browser,
+such that the browser navigates to the appropriate section of
 the manual.
 
 If the
@@ -82168,6 +82168,31 @@ successfully invokes the URL-opening mechanism, it returns
 .codn t .
 Otherwise, it throws an error exception.
 
+The web browser is invoked using a system-dependent strategy.
+On MS Windows, the
+.code ShellExecuteW
+function is relied upon to open the URL.
+
+On other platforms, if the
+.code BROWSER
+environment variable exists, its value is assumed to indicate the
+name or path of the web browsing program which can accept the URL
+as an argument. If this variable doesn't exist, then
+.code doc
+searches for a system-dependent URL-opening utility, such as
+.codn xdg-open .
+If this utility is not found, then
+.code doc
+tries to fall back searching for a browser using one of several names.
+If no URL-opening mechanism is identified using the above strategies, an error
+exception is thrown. However, if the mechanism is identified, but does not
+successfully dispatch the URL to a browser, there is no requirement to thrown
+an error exception. It may appear that the
+.code doc
+function returns
+.code t
+but has no effect.
+
 .coNP Function @ quip
 .synb
 .mets (quip)