Date: Sat, 02 Jan 2010 17:38:31 +0100
From: Uwe Ligges <ligges at statistik.tu-dortmund.de>
Steve Rowley wrote:
Is there any way to do this from the Windows binary .zip files, or from the installations
generated thereby?
Well, internally, you can do somewthing as R's help system does, but it
is documented to be subject to change ("As they are mainly intended for
internal use, their interfaces are subject to change."), see ?Rd2HTML
For package pkg in directory c:/dir on help topic foo you could ask
Rd2HTML(tools:::fetchRdDB("c:/dir/pkg/help/pkg", "foo")) in order to get
a HTML representation. See ?Rd2HTML for details on how to control stuff.
Thanks, tools:::fetchRdDB() was the clue I needed. I understand the
frightening triple colon means this bit of magic is internal, and
likely to change at a moment's notice. Using it wasn't exactly
trivial, either: see the code below for how I generated the static
HTML for all installed packages.
Since wanting static HTML help pages for bookmarking or reading while
R is not running sounds kind of reasonable, it would be nice if
something like this were available for Windows users of R. It would
be a shame if everybody else had to figure this out in detail, too.
Again, thanks for the pointer. R is fun again! :-)
------------------------------
library("tools") # fetchRdDB(), Rd2HTML(), et al.
makeStaticHTMLHelp <- function(libs = .libPaths(), verbose = TRUE) {
maybeCat <- function(msg, ...) { if (verbose) cat(sprintf(msg, ...)) }
subDirectories <- function(d) { # Directories under d (not files!)
basename(rownames(subset(file.info(dir(path = d, full.names = TRUE)), subset = isdir)))
} #
makeHTML <- function(pkgRdDB, lib, pkg, key, links) {# Write key's doc to an html file
Rd2HTML(pkgRdDB[[key]], # extract doc from Rd data
out = file.path(lib, pkg, "html", paste(key, "html", sep = ".")),
package = pkg, # use this pkg's name
Links = links, # use HTML links if non-null
no_links = is.null(links), # no links if arg is null
stages = c("install","render"), # run appropriate Sexpr forms
outputEncoding = "", # native encoding of this system
dynamic = FALSE) # this is, of course, static
} #
## *** NB: make.packages.html() prints a message even if verbose == FALSE?!
maybeCat(if (make.packages.html(lib.loc = libs, verbose = verbose))
"done.\n" # Succeeded updating packages.html file
else # But success is apparently not always
"FAILED?!\n") # guaranteed!
maybeCat("Finding HTML links... ") # Find HTML links between doc pages
links <- findHTMLlinks() # just 1ce, outside the loops below
maybeCat("found %d links... done.\n", length(links)) #
sapply(libs, function(lib) { # Map over libraries
maybeCat("Generating static HTML for packages in library %s...\n", lib)
sapply(subDirectories(lib), function(pkg) { # Map over packages in this library
maybeCat(" package %s... ", pkg) # Fetch pkg's Rd docs (for ALL keys)
tryCatch({ # In case can't read .rdb file
pkgRdDB <- tools:::fetchRdDB(file.path(lib, pkg, "help", pkg), key = NULL)
sapply(names(pkgRdDB), function(key) { # Map over keys in this pkg's docs
tryCatch(makeHTML(pkgRdDB, lib, pkg, key, links),
error = function(e) { # If error, retry w/o links
maybeCat("retrying %s without links... ", key)
tryCatch(makeHTML(pkgRdDB, lib, pkg, key, NULL),
error = function(e) { maybeCat("FAILED without links?! ") })
}) #
}) # Done with this key
}, error = function(e) { maybeCat("Couldn't read .rdb file?! ") })
maybeCat("done.\n") # Done with this package
}) # Done with this library
}) # Done.
invisible(NA) # Return nothing of interest
} #
------------------------------