help.start(lib.loc = .); also verbose; options(html_lib.loc = *)

git-svn-id: https://svn.r-project.org/R/trunk@88167 00db46b3-68df-0310-9c12-caf00c1e9a41

Author: maechler

doc/NEWS.Rd

@@ -18,6 +18,11 @@
 
       \item \code{terms(<formula>, specials = *)} now treats non-syntactic
       specials more gracefully, thanks to \I{Mikael Jagan}'s \PR{18568}.
+
+      \item \code{help.start()} gets a \code{lib.loc} option and its
+      default for \code{make.packages.html()} is enhanced to allow, e.g.,
+      fast access to \code{.Library} when that contains only base and
+      recommended packages.
     }
   }
 
@@ -41,7 +46,6 @@
 
   \subsection{UTILITIES}{
     \itemize{
-      % this will not be ported to R 4.5.0.
       \item \command{R CMD check} now reports further \command{clang} warnings
       including \code{-Wkeyword-macro}.  This is most commonly seen for
       the C23 keywords \code{bool}, \code{true} and \code{false}, but is

src/library/utils/R/help.start.R

@@ -1,7 +1,7 @@
 #  File src/library/utils/R/help.start.R
 #  Part of the R package, https://www.R-project.org
 #
-#  Copyright (C) 1995-2022 The R Core Team
+#  Copyright (C) 1995-2025 The R Core Team
 #
 #  This program is free software; you can redistribute it and/or modify
 #  it under the terms of the GNU General Public License as published by
@@ -18,19 +18,24 @@
 
 help.start <-
     function (update = FALSE, gui = "irrelevant",
-              browser = getOption("browser"), remote = NULL)
+              lib.loc = .libPaths(),
+              browser = getOption("browser"), remote = NULL,
+              verbose = getOption("verbose"))
 {
     WINDOWS <- .Platform$OS.type == "windows"
     if (!WINDOWS) {
         ## should always be set, but might be empty
         if (!is.function(browser) &&
             (length(browser) != 1L || !is.character(browser) || !nzchar(browser)))
+
             stop("invalid browser name, check options(\"browser\").")
     }
+    if(!missing(lib.loc)) # --> default for make.packages.html(lib.loc = *), as called from httpd()
+        options(html_lib.loc = lib.loc)
     home <- if (is.null(remote)) {
         port <- tools::startDynamicHelp(NA)
         if (port > 0L) {
-            if (update) make.packages.html(temp = TRUE)
+            if (update) make.packages.html(lib.loc = lib.loc, temp = TRUE)
             paste0("http://127.0.0.1:", port)
         } else stop("help.start() requires the HTTP server to be running",
                     call. = FALSE)
@@ -46,11 +51,12 @@ help.start <-
                            exdent = 4L))
         writeLines(gettext("Otherwise, be patient ..."))
     }
-    browseURL(url, browser = browser)
+    browseURL(url, browser=browser, verbose=verbose)
     invisible()
 }
 
-browseURL <- function(url, browser = getOption("browser"), encodeIfNeeded=FALSE)
+browseURL <- function(url, browser = getOption("browser"), encodeIfNeeded=FALSE,
+                      verbose = getOption("verbose"))
 {
     WINDOWS <- .Platform$OS.type == "windows"
 
@@ -78,7 +84,9 @@ browseURL <- function(url, browser = getOption("browser"), encodeIfNeeded=FALSE)
       isLocal <- TRUE
     else
       isLocal <- FALSE
-
+    if(verbose)
+        cat(sprintf("browseURL() on unix-alike: browser='%s', isLocal=%s:\n",
+                    browser, as.character(isLocal)))
     ## escape characters.  ' can occur in URLs, so we must use " to
     ## delimit the URL.  We need to escape $, but "`\ do not occur in
     ## valid URLs (RFC 2396, on the W3C site).
@@ -96,6 +104,8 @@ browseURL <- function(url, browser = getOption("browser"), encodeIfNeeded=FALSE)
                          gsub("([,)$])", "%\\1", url), ")\"")
                }, quotedUrl)
     else quotedUrl
-    system(paste(browser, remoteCmd, "> /dev/null 2>&1 ||",
-                 browser, quotedUrl, "&"))
+    cmd <- paste(browser, remoteCmd, "> /dev/null 2>&1 ||",
+                 browser, quotedUrl, "&")
+    if(verbose) cat(sprintf("system(<cmd>), <cmd> := '%s'", cmd))
+    system(cmd)
 }

src/library/utils/R/linkhtml.R

@@ -1,7 +1,7 @@
 #  File src/library/utils/R/linkhtml.R
 #  Part of the R package, https://www.R-project.org
 #
-#  Copyright (C) 1995-2022 The R Core Team
+#  Copyright (C) 1995-2025 The R Core Team
 #
 #  This program is free software; you can redistribute it and/or modify
 #  it under the terms of the GNU General Public License as published by
@@ -18,7 +18,8 @@
 
 
 make.packages.html <-
-    function(lib.loc = .libPaths(), temp = FALSE, verbose = TRUE,
+    function(lib.loc = getOption("html_lib.loc", default = .libPaths()),
+             temp = FALSE, verbose = TRUE,
              docdir = R.home("doc"))
 {
     add_lib_index <- function(libs)

src/library/utils/man/browseURL.Rd

@@ -1,6 +1,6 @@
 % File src/library/utils/man/browseURL.Rd
 % Part of the R package, https://www.R-project.org
-% Copyright 1995-2022 R Core Team
+% Copyright 1995-2025 R Core Team
 % Distributed under GPL 2 or later
 
 \name{browseURL}
@@ -11,7 +11,8 @@
 }
 \usage{
 browseURL(url, browser = getOption("browser"),
-          encodeIfNeeded = FALSE)
+          encodeIfNeeded = FALSE,
+          verbose = getOption("verbose"))
 }
 \arguments{
   \item{url}{a non-empty character string giving the URL to be loaded.
@@ -31,6 +32,8 @@ browseURL(url, browser = getOption("browser"),
     itself does encoding, and can be harmful for \samp{file://} URLs on some
     systems and for \samp{http://} URLs passed to some CGI applications.
     Fortunately, most URLs do not need encoding.}
+  \item{verbose}{logical indicating if information about the system
+    interface should be printed to the console.}
 }
 \details{
   \describe{
@@ -41,12 +44,12 @@ browseURL(url, browser = getOption("browser"),
   made manually or automatically when \R was configured.  (See
   \code{\link{Startup}} for where to override that default value.)
   To suppress showing URLs altogether, use the value \code{"false"}.
-  
+
   On many platforms it is best to set option \code{"browser"} to a
   generic program/script and let that invoke the user's choice of
   browser.  For example, on macOS use \command{open} and on many other
   Unix-alikes use \command{xdg-open}.
-  
+
   If \code{browser} supports remote control and \R knows how to perform
   it, the URL is opened in any already-running browser or a new one if
   necessary.  This mechanism currently is available for browsers which
@@ -67,7 +70,7 @@ browseURL(url, browser = getOption("browser"),
   (see \code{\link{URLencode}}).
 
   To suppress showing URLs altogether, set \code{browser = "false"}.
-  
+
   The behaviour for arguments \code{url} which are not URLs is
   platform-dependent.  Some platforms accept absolute file paths; fewer
   accept relative file paths.
@@ -106,7 +109,7 @@ browseURL("file://d:/R/R-2.5.1/doc/html/index.html",
   \samp{mailto:} may or may not (and if it does may not use the user's
   preferred email client).  However, modern browsers are unlikely to handle
   \samp{ftp://}.
-  
+
   For the \samp{file://} scheme the format accepted (if any) can depend on
   both browser and OS.
 }

src/library/utils/man/help.start.Rd

@@ -1,6 +1,6 @@
 % File src/library/utils/man/help.start.Rd
 % Part of the R package, https://www.R-project.org
-% Copyright 1995-2024 R Core Team
+% Copyright 1995-2025 R Core Team
 % Distributed under GPL 2 or later
 
 \name{help.start}
@@ -12,20 +12,26 @@
 }
 \usage{
 help.start(update = FALSE, gui = "irrelevant",
-           browser = getOption("browser"), remote = NULL)
+           lib.loc = .libPaths(),
+           browser = getOption("browser"), remote = NULL,
+           verbose = getOption("verbose"))
 }
 \arguments{
   \item{update}{logical: should this attempt to update the package index to
     reflect the currently available packages.  (Not attempted if
     \code{remote} is non-\code{NULL}.)}
   \item{gui}{just for compatibility with S-PLUS.}
+  \item{lib.loc}{character vector, listing the package libraries to be included.}
   \item{browser}{the name of the program to be used as hypertext
     browser.  It should be in the \env{PATH}, or a full path specified.
     Alternatively, it can be an \R function which will be called with a
     URL as its only argument. This option is normally unset on Windows,
     when the file-association mechanism will be used.}
-  \item{remote}{A character string giving a valid URL for the
-    \file{\var{\link{R_HOME}}} directory on a remote location.}
+  \item{remote}{a character string giving a valid URL for the
+    \file{\var{\link{R_HOME}}} directory on a \dQuote{remote} location;
+    may be \code{"file://<Rhome>"} pointing to a path on your local platform.}
+  \item{verbose}{logical indicating if information about the system
+    interface should be printed to the console.}
 }
 \details{
   Unless \code{remote} is specified this requires the HTTP server to be
@@ -50,6 +56,7 @@ help.start(update = FALSE, gui = "irrelevant",
 \seealso{
   \code{\link{help}()} for on- and off-line help in other formats.
 
+  \code{\link{make.packages.html}} for how the \file{*.html} pages are created.
   \code{\link{browseURL}} for how the help file is displayed.
 
   \code{\link{RSiteSearch}} to access an on-line search of \R resources.

src/library/utils/man/make.packages.html.Rd

@@ -1,20 +1,21 @@
 % File src/library/utils/man/unix/make.packages.html.Rd
 % Part of the R package, https://www.R-project.org
-% Copyright 1995-2011 R Core Team
+% Copyright 1995-2025 R Core Team
 % Distributed under GPL 2 or later
 
 \name{make.packages.html}
 \alias{make.packages.html}
 \title{Update HTML Package List}
 \usage{
-make.packages.html(lib.loc = .libPaths(), temp = FALSE,
-                   verbose = TRUE, docdir = R.home("doc"))
+make.packages.html(lib.loc = getOption("html_lib.loc", default = .libPaths()),
+                   temp = FALSE, verbose = TRUE, docdir = R.home("doc"))
 }
 \description{
   Re-create the HTML list of packages.
 }
 \arguments{
-  \item{lib.loc}{character vector.  List of libraries to be included.}
+  \item{lib.loc}{character vector of package libraries to be
+    included.  Default typically set from \code{\link{help.start}(lib.loc = *)}.}
   \item{temp}{logical: should the package indices be created in a
     temporary location for use by the HTTP server?}
   \item{verbose}{logical.  If true, print out a message.
@@ -54,6 +55,8 @@ make.packages.html(lib.loc = .libPaths(), temp = FALSE,
 \examples{\dontrun{
 make.packages.html()
 # this can be slow for large numbers of installed packages.
-}}
-
+}
+if(interactive()) # typically fast and quiet
+  make.packages.html(lib.loc = .Library, verbose=FALSE)
+}
 \keyword{utilities}