internal latex-help utils: modularize + msg argument

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

Author: maechler

src/library/utils/R/help.R

@@ -1,7 +1,7 @@
 #  File src/library/utils/R/help.R
 #  Part of the R package, https://www.R-project.org
 #
-#  Copyright (C) 1995-2016 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
@@ -88,13 +88,15 @@ function(topic, package = NULL, lib.loc = NULL,
 	      class = "help_files_with_topic")
 }
 
-print.help_files_with_topic <- function(x, ...)
+print.help_files_with_topic <- function(x, ...) # ...  may contain  msg=FALSE
 {
-    browser <- getOption("browser")
     topic <- attr(x, "topic")
-    type <- attr(x, "type")
-    if (.Platform$GUI == "AQUA" && type == "html")
-        browser <- get("aqua.browser", envir = as.environment("tools:RGUI"))
+    type  <- attr(x, "type")
+    if(type == "html")
+        browser <- 
+            if (.Platform$GUI == "AQUA" && type == "html")
+                get("aqua.browser", envir = as.environment("tools:RGUI"))
+            else getOption("browser")
     paths <- as.character(x)
     if(!length(paths)) {
         writeLines(c(gettextf("No documentation for %s in specified packages and libraries:",
@@ -104,7 +106,7 @@ print.help_files_with_topic <- function(x, ...)
         return(invisible(x))
     }
 
-    port <- if(type == "html") tools::startDynamicHelp(NA) else NULL
+    if(type == "html") port <- tools::startDynamicHelp(NA)
 
     if(attr(x, "tried_all_packages")) {
         paths <- unique(dirname(dirname(paths)))
@@ -174,7 +176,7 @@ print.help_files_with_topic <- function(x, ...)
                     tmp[tools::file_path_sans_ext(tmp$File) == tp[i], "Title"]
                 }
                 txt <- paste0(titles, " {", basename(paths), "}")
-                ## the default on menu() is currtently graphics = FALSE
+                ## the default on menu() is currently graphics = FALSE
                 res <- menu(txt, title = gettext("Choose one"),
                             graphics = getOption("menu.graphics"))
                 if(res > 0) file <- p[res]
@@ -215,25 +217,21 @@ print.help_files_with_topic <- function(x, ...)
             texinputs <- file.path(dirpath, "help", "figures")
             tf2 <- tempfile("Rlatex")
             tools::Rd2latex(.getHelpFile(file), out = tf2)
-            .show_help_on_topic_offline(tf2, topic, type, texinputs)
+            .show_help_on_topic_offline(tf2, topic, type, texinputs, ...)
             unlink(tf2)
         }
     }
-
     invisible(x)
 }
 
-.show_help_on_topic_offline <-
-    function(file, topic, type = "pdf", texinputs = NULL)
-{
-    encoding <-""
+.help_topic_latex <- function(file, topic) { # Side effect: creates file  <topic>.tex in working directory
     lines <- readLines(file)
     encpatt <- "^\\\\inputencoding\\{(.*)\\}$"
-    if(length(res <- grep(encpatt, lines, perl = TRUE, useBytes = TRUE)))
-        encoding <- sub(encpatt, "\\1", lines[res],
-                        perl = TRUE, useBytes = TRUE)
+    encoding <- if(length(res <- grep(encpatt, lines,
+                                      perl = TRUE, useBytes = TRUE, value = TRUE)))
+                    sub(encpatt, "\\1", res, perl = TRUE, useBytes = TRUE)
+                else ""
     texfile <- paste0(topic, ".tex")
-    on.exit(unlink(texfile)) ## ? leave to helper
     if(nzchar(opt <- Sys.getenv("R_RD4PDF"))) opt else "times,inconsolata"
     has_figure <- any(grepl("\\Figure", lines))
     cat("\\documentclass[", getOption("papersize"), "paper]{article}\n",
@@ -245,11 +243,19 @@ print.help_files_with_topic <- function(x, ...)
         file = texfile, sep = "")
     file.append(texfile, file)
     cat("\\end{document}\n", file = texfile, append = TRUE)
-    helper <- if (exists("offline_help_helper", envir = .GlobalEnv))
-        get("offline_help_helper", envir = .GlobalEnv)
-    else offline_help_helper
-    if (has_figure) helper(texfile, type, texinputs)
-    else helper(texfile, type)
+    texfile
+}
+
+## "static": _only_ called once above for type == "pdf" : currently  "offline" <==> {latex -> pdf}
+.show_help_on_topic_offline <-
+    function(file, topic, type = "pdf", texinputs = NULL, msg = TRUE)
+{
+    texfile <- .help_topic_latex(file, topic)
+    on.exit(unlink(texfile)) ## ? leave to helper
+    helper <- get0("offline_help_helper", envir = .GlobalEnv) %||% offline_help_helper # <-> below
+    if (has_figure)
+         helper(texfile, type, texinputs=texinputs, msg=msg)
+    else helper(texfile, type,                      msg=msg)
     invisible()
 }
 
@@ -268,7 +274,7 @@ print.help_files_with_topic <- function(x, ...)
 }
 
 
-offline_help_helper <- function(texfile, type, texinputs = NULL)
+offline_help_helper <- function(texfile, type, texinputs = NULL, msg = TRUE)
 {
     ## Some systems have problems with texfile names like ".C.tex"
     tf <- tempfile("tex", tmpdir = ".", fileext = ".tex"); on.exit(unlink(tf))
@@ -280,11 +286,10 @@ offline_help_helper <- function(texfile, type, texinputs = NULL)
         stop(gettextf("creation of %s failed", sQuote(ofile2)), domain = NA)
     if(file.copy(ofile, ofile2, overwrite = TRUE)) {
         unlink(ofile)
-        message(gettextf("Saving help page to %s", sQuote(basename(ofile2))),
-                domain = NA)
-    } else {
-        message(gettextf("Saving help page to %s", sQuote(ofile)), domain = NA)
+        if(msg) ofile <- basename(ofile2)
     }
+    if(msg)
+        message(gettextf("Saving help page to %s", sQuote(ofile)), domain = NA)
     invisible()
 }