Skip to content

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

28 messages · Uwe Ligges, Steve Rowley, Michael Friendly +7 more

Messages 1–25 of 28

#
Steve Rowley wrote:
Ah, sorry, I must have missed your reply.

WEell, 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.

Uwe Ligges
4 days later
#
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 wrote:
Thanks for that code. I fully agree that the current help system is a step
back. For stable bookmarking, my workaround is to put

options(help.ports=6800)

into the profile,  so I can created links like

http://127.0.0.1:6800/library/gmodels/html/estimable.html

but this still required that I start RGui and the help system once. Thanks
to Duncan Murdoch who implmented this.

http://markmail.org/message/mvpgkwctacpl6fl4

Dieter
#
On 7.1.2010 9:49, Dieter Menne wrote:
Thanks for this, too. Btw, is there a way to start the dynamic Rhelp server in the background without manually launching RGui? That, combined with Dieter's suggestion, would bring the help system sort of back to its original state. 

I am sorry to say that the new dynamic help is a HUGE nuisance to me. Had to revert back to R 2.9 because of that :-(.

Michal
#
Michal Kulich wrote:
You don't need Rgui, you could run Rterm, which would have a smaller 
footprint. It's not very hard to start it and minimize it, but if you 
want it running invisibly, you'll need to figure out how to hide the icon.

A disadvantage of doing this is that you won't see help relevant to your 
current session, you'll see help relevant to the background task.  In 
2.10.x there aren't many differences, but you'll find it more limiting 
in 2.11.x and later.

Duncan Murdoch
#
Michal Kulich wrote:
I too have reverted to 2.9.2 on Win XP because I find html help to be 
far less convenient than the compiled CHM help I had before. CHM help is
so much easier because the Contents, Index and Search panels make it 
easy to *see* all the items defined for a package, and I get a separate 
help window for each package.
I very much appreciate the efforts of the R-core team to move R forward,
but I think the change in help is a step back.
#
On 07/01/2010 9:05 AM, Michael Friendly wrote:
You can see the items for the package on the index page for the package, 
which is linked from every page.

You can put together a package that displays the help in your favourite 
format, if you don't like the default format.  There's nothing that we 
used in CHM help that couldn't be duplicated in Javascript, without the 
security holes.

I see it as more important that R core enables others to do what they 
want, rather than to maintain ancient designs.

Duncan Murdoch
#
On 7.1.2010 12:18, Duncan Murdoch wrote:
This works. Not entirely invisible but not a big deal about that.
The R code run within Rterm is

options(help_type="html",help.ports=6800)
help.start()
library(audio)
wait(-1)

[couldn't find another way to hang R indefinitely in batch mode]
Not a problem if one is not switching between different versions of R. The current version is on the path and the path will get updated (manually) after a new version is installed. Thus, the relevant help will be always displayed.

Thanks, this is a kind of solution. Now I can use bookmarks to HTML help for the favorite libraries when working in ESS - the impossibility to set those and the need to start Rgui was the big nuisance. 

I am sure the new help system will get gradually improved in the future.

Best,

Michal
#
On Thu, Jan 7, 2010 at 9:20 AM, Duncan Murdoch <murdoch at stats.uwo.ca> wrote:
Perhaps the link to the Index could be placed at both the top and
bottom rather than just at the bottom since its a nuisance to have to
scroll down and its less noticeable at the bottom as its typically off
the screen.
#
On 07/01/2010 9:47 AM, Michal Kulich wrote:
Not necessarily.  The current help system can display information about 
the current session, e.g. the result of ls(), as a simple example.  But 
if you use a single background session you won't get relevant information.

Duncan Murdoch
#
On 07/01/2010 9:51 AM, Gabor Grothendieck wrote:
Yes, I may do that at some point, to make the layout of the help pages 
more consistent.  Most "higher level" pages have a consistent header 
(more so in R-devel), but the individual topic pages don't.

What I'd really like is for someone who has good taste to redesign the 
look of the whole system.  I think one or two people are working on 
packages to do this, and I'd much rather spend time providing whatever 
low level support they need, rather than doing it myself.

Duncan Murdoch
#
On 7.1.2010 15:52, Duncan Murdoch wrote:
Sorry, I must admit I don't get it.
#
On 07/01/2010 10:00 AM, Michal Kulich wrote:
A more useful example than ls() would be methods().   I think it would 
be nice to have a list of methods included in the man page for a generic 
function, and links to their pages if they have their own man pages.  
You might want to list all installed methods, with some sort of 
highlighting to indicate which ones are already attached, or perhaps be 
able to toggle between installed and attached, or whatever.  None of 
that is possible with static help, not even a list of installed methods, 
because someone might install a new package that offers some others 
after the static help has already been built.

You just need to use some imagination.

Duncan Murdoch
#
For what it is worth, I would gladly sacrifice this capability in
order to be able to consult all my R help pages through a Firefox
bookmark to the packages listing (which is what I used to do, and will
do again, when I get time to either rebuild from source or get the
forthcoming Fedora RPM, which will have static pages as the default),
without starting an R session.

Jon
On 01/07/10 10:32, Duncan Murdoch wrote:
#
On 07/01/2010 11:36 AM, Jonathan Baron wrote:
What's so hard about leaving an R session running, and using bookmarks 
as Dieter described?

Duncan Murdoch
#
On 07/01/2010 2:16 PM, Kevin Wright wrote:
You weren't following Dieter's instructions, then.
Then contribute a new one.
Then fix the search tool so it can search dynamic web pages.  They can 
be spidered too, just like static ones.

Duncan Murdoch
#
On 07/01/2010 2:58 PM, Kevin Wright wrote:
I don't like the fragmentation of the R help system.  This just produces 
yet another set of pages which are not reachable from anywhere but one 
place.

The help system should be a network of pages which are all 
interconnected.  I should be able to click on something in the ?plot 
page and get to the ?plot.formula page (which I can do now, based on a 
static link) or the ?plot.foo page (which hasn't been written yet, but 
will be by the time I look at ?plot).

Duncan Murdoch
#
Have you looked at adding zeroconf suport to the server?  That would
mean you could navigate to (e.g.) http://r-help.local to get to the R
docs.

Hadley
#
And this would be pretty easy to, since you can program it in R.
There are heaps of possibilities - you could use do clustering based
on documentation text to automatically suggested related documentation
across all packages.

Hadley
#
On 7.1.2010 20:22, Duncan Murdoch wrote:

            
I see. Well, I never lacked any of these capabilities... Please understand that people who use R to do their work may have different objectives than the developers - and they form the majority of R users.
Indeed, but that option is not documented, as far as I know - at least not in 2.10.0. And even if it was, most users would not be able to find it or use it because they have no clue what a port is.
Duncan, if even the quite advanced and computer-proficient users have trouble using the dynamic R help and have to resort to some quite complex and cumbersome home-made solutions to get back the basic functionality then something is not right. It's true that the help system was never a particular strength of R and that it needed an overhaul. What worked well in the late 90's with a few dozen packages does not work well with >1000 packages. However, 2.10.x does not seem to make things better.

The work of the R developers should be widely appreciated and we really do appreciate it. The question is whether their effort is extended in the best direction... (Imho, that's an issue with most open-source projects and it's been much worse with Mozilla than with R).

Just my 2c.

Michal
#
Duncan Murdoch wrote:
It pollutes my space, and I am a Window-closing maniac, so it won't survive
the next attack.

<http://www.microsoft.com/downloads/en/confirmation.aspx?familyId=9d467a69-57ff-4ae7-96ee-b18c4790cffd&displayLang=en>

It might be worth a try to use instsrv and srvany to install the batch as a
server. The resource kit cries out loud when installed on Window 7 for being
a stupid old dinosaur, but in similar case I could still use it.

Dieter
#
Michal Kulich wrote:
Then they should contribute to the development.  I don't owe you 
anything.  You owe us a lot.

Duncan Murdoch
#
Dieter Menne wrote:
If that works, writing up instructions would be a useful contribution.

Duncan Murdoch