[R] Building static HTML help pages in R 2.10.x on Windows

[Steve Rowley]

>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
}                                                      # 
------------------------------

-- 
Steve Rowley <sgr at alum.mit.edu> http://alum.mit.edu/www/sgr/ Skype: sgr000