[R] user library help functionality (packages.html)

[Duncan Murdoch]

On 1/15/2009 3:17 PM, Jarrett Barber wrote:
> This helps a lot.  I have options(htmlhelp=TRUE) and  
> options(chmhelp=FALSE) (else problems).  Now, ?, help(), and  
> help.search() seem to work well.  But, help.start() appears restricted  
> to packages in the site library.  I see, in the Help/FAQ on R for  
> Windows/ Sections 4.3 and 4.4, that I cannot expect more from  
> help.start() unless I have write permission to $RHOME/library, which I  
> do not (package does have a CONTENTS file however).  I assume that, if  
> I want my students to have this functionality, they, too, would need  
> write access to $RHOME/library, correct?  But, this does not seem a  
> wise thing to give.  Am I missing something here, barring permission  
> changes, that would allow help.search() to see user libraries?  

You mean help.start() here, don't you?  help.search() does see 
everything in the libraries listed in .libPaths().


This
> would be ideal, but your suggestions seems to give us nice help  
> functionality, and I think we can implement an R installation campus- 
> wide without the full functionality of help.seach().  Thanks very much.

As far as I know on Windows there's currently no way to get help.start() 
to go to a personalized page.  The stuff that it refers to all lives in 
RHOME/doc/html, and many of the links in the files it works with assume 
that they are installed in the same hierarchy.

I'm not sure if things are different on Unix, where we use soft links to 
make all the package directories appear to be under one parent.

Duncan Murdoch

> Jarrett
> 
> 
> R Session:
> 
> R version 2.7.0 (2008-04-22)
> ...snip...
>  > personalLib<- .libPaths()[1]; personalLib
> [1] "H:\\Desktop\\RFiles\\Library"
>  > getOption("htmlhelp")
> [1] TRUE
>  > getOption("chmhelp")
> [1] FALSE
>  > install.packages("UsingR",
> + lib=personalLib,
> + depend=TRUE)
> trying URL 'http://streaming.stat.iastate.edu/CRAN/bin/windows/contrib/2.7/UsingR_0.1-10.zip'
> Content type 'application/zip' length 1433201 bytes (1.4 Mb)
> opened URL
> downloaded 1.4 Mb
> 
> package 'UsingR' successfully unpacked and MD5 sums checked
> 
> The downloaded packages are in
>          C:\Temp\RtmpQr4t3E\downloaded_packages
> updating HTML package descriptions
> Warning message:
> In file.create(f.tg) :
>    cannot create file 'C:\PROGRA~1\R\R-27~1.0/doc/html/packages.html',  
> reason 'Permission denied'  ## PERMISSION PROBLEM
>  > library("UsingR")
> Warning message:
> package 'UsingR' was built under R version 2.7.2
>  > help("UsingR") ## works!
> Help for ëUsingRí is shown in the browser
>  > help.start() ## restricted to site library
> updating HTML package listing
> updating HTML search index
> fixing URLs in non-standard libraries
> If nothing happens, you should open 'C:\PROGRA~1\R\R-27~1.0\doc\html 
> \index.html' yourself
> Warning message:
> In file.create(f.tg) :
>    cannot create file 'C:\PROGRA~1\R\R-27~1.0/doc/html/packages.html',  
> reason 'Permission denied' ## SAME PERMISSION PROBLEM
>  > help.search("UsingR") ## works!
>  > ?UsingR ## works!
> Help for ëUsingRí is shown in the browser
>  > q()
> 
> 
> On Jan 15, 2009, at 11:42 AM, Duncan Murdoch wrote:
> 
>> On 1/15/2009 12:50 PM, Jarrett Barber wrote:
>>> Here's another help file question.
>>> Some context: University setting wherein R is installed for   
>>> availability to students and course instructors across campus in   
>>> various PC labs.  Windows Vista environment.
>>> Goal: To maximize flexibility and functionality of installing add- 
>>> on  packages and associated help files among different users,  
>>> while  avoiding conflicts across different user libraries.  (I  
>>> could have my  difficult-to-access sysadmin install _all_  
>>> libraries, but this seems  wasteful, and would seem to present  
>>> problems when my colleague or I  want to update a package or  
>>> install a newly available package but do  not have time to wait a  
>>> week or two for our sysadmin.)
>>> Problem (?): As a course instructor, I want flexibility to install  
>>> add- on libraries to a user (not site) library, and I don't want to  
>>> step on  my colleagues' toes (or vice-versa) when it comes to add- 
>>> on packages  and associated help files for use in classes.  I have  
>>> no problem  installing add-on packages to a user library, with one  
>>> exception: I do  not have permission to update the file $RHOME/doc/ 
>>> html/packages.html,  as evidenced by a permission error upon  
>>> installing a package to a user  library using update.packages (not  
>>> to the default site library, which  is also restricted).  The  
>>> installed add-on packages work fine, with  the exception of some of  
>>> the help functionality.  I find myself having  to use browseURL()  
>>> to point to the html files in the package's file  structure.  I  
>>> cannot expect the average student (or senior colleague)  to  
>>> tolerate this situation.
>>
>> A simpler way to get to the HTML man pages is to run
>>
>> options(htmlhelp=TRUE)
>>
>> and then the regular ?topic or help("topic") will find the HTML help  
>> pages in your local library.
>>
>>> I'm thinking that I simply need to have my sysadmin give me and my   
>>> colleagues (all users who want to install add-ons packages?)   
>>> permission to read/write packages.html, and the problem will go  
>>> away.   But, before I ask my sysadmin to give permission, I want to  
>>> know, does  this create another problem?  For example, my colleague  
>>> creates a  library for STAT3000BC, which, I assume, will modify  
>>> packages.html  (assuming my sysadmin gives permission), then I  
>>> create a library for  STAT2010, which also modifies packages.html.   
>>> See my concern?  Does R  somehow allow harmonious help  
>>> functionality in such cases (by, for  example, maintaining separate  
>>> copies of packages.html for different  users)?
>>
>> You will likely have strange problems if you do that.  The doc/html/ 
>> packages.html file is intended to talk about what is available to  
>> everyone; I suspect in your scenario, it would be updated to show  
>> your packages (but not your colleague's) whenever you added one, and  
>> then updated to show your colleague's packages (but not yours) when  
>> he added one, and would almost never be right for both of you.
>>
>> The good news is that it looks as though sometime this year we will  
>> make quite substantial changes to the way the help system is stored,  
>> so a lot of things like packages.html could be generated on the fly.
>>
>> Duncan Murdoch
>